PinionAI API

This document provides details about the API endpoints available in the PinionAI API agent service.

Authentication

Most endpoints require a Bearer token in the Authorization header for authentication.

Authorization: Bearer <YOUR_ACCESS_TOKEN>

---

Endpoint Summary

Method	Path	Auth	Description
GET	/agent/:uid	Yes	Start a new agent session from an agent UID
GET	/agentlist	Yes	Retrieve a list of active agents with their IDs and descriptions
GET	/version/:uid	Yes	Start a new agent session from the latest version
GET	/version/:uid/:version_type	Yes	Start a new agent session from a specific version type
POST	/agent	No	Update agent data (stub implementation)
POST	/token	No	Create a bearer token using client credentials
POST	/session	Yes	Create or update a session with session data
GET	/session/:uid	Yes	Get session details by UID
GET	/session/:uid/lastmodified	Yes	Get session last modified timestamp
GET	/customer/:value	Yes	Get customer by phone, email, or UID
POST	/customer	Yes	Create a new customer
POST	/customer/:uid	Yes	Update an existing customer
GET	/filesession/:uid	Yes	Create an empty session for an agent UID
POST	/filesession	No	Create a session using a version key and return a generated token
POST	/transaction	Yes	Create a new transaction record
GET	/transaction/:shortened	No	Retrieve transaction and form config by shortened token
PUT	/transaction/:uid	No	Update transaction status and response message
POST	/connector	Yes	Retrieve an auth token for a connector
POST	/vconnector	Yes	Retrieve a connector client secret
POST	/database	Yes	Retrieve database connector details
GET	/.well-known/oauth-authorization-server	No	RFC 8414 OAuth 2.0 Authorization Server Metadata (automated discovery)
GET	/.well-known/oauth-protected-resource	No	RFC 9728 OAuth 2.0 Protected Resource Metadata (links resource to its auth server)
GET	/mcp/sse	Yes	Connect to Model Context Protocol (MCP) server stream (SSE)
POST	/mcp/message	Yes*	Handle incoming MCP client JSON-RPC messages (requires active sessionId as query parameter)
POST	/mcp	Yes	Modern, stateless Model Context Protocol (MCP) Streamable HTTP endpoint
POST	/formname	Yes	Retrieve form fields from forms table by name
POST	/status	Yes	Retrieve transaction status and response message for a specific transaction

---

Endpoints

1. Start Agent Session

• Endpoint: GET /agent/:uid
• Method: GET
• Description: Starts a new agent session by loading agent data for the requested UID and creating a session record.
• Authorization: Bearer token required.
• Path Parameters:
• uid (string, required): Agent UID.
• Response:
• 200 OK with session metadata and raw session data.
• 400 Bad Request if the UID is invalid.
• 401 Unauthorized if the authorization header is missing, malformed, invalid, or expired.
• 404 Not Found if the agent does not exist.
• 500 Internal Server Error on database or session creation failures.

Example response:

{
  "success": true,
  "message": "Agent started successfully",
  "data": {
    "uid": "session_uid",
    "customer_uid_fk": null,
    "agent_uid_fk": "agent_id",
    "account_uid_fk": "account_id",
    "session_data": {
      "agent": {
        "agentId": "..."
      }
    },
    "created": "...",
    "lastmodified": "..."
  }
}

1a. Retrieve Agent List

• Endpoint: GET /agentlist
• Method: GET
• Description: Retrieves a list of active agents associated with the authorized account, sorted alphabetically by name.
• Authorization: Bearer token required.
• Response:
• 200 OK with a JSON payload containing the success flag and the list of active agents with their unique IDs, names, and descriptions.
• 401 Unauthorized if the authorization header is missing, malformed, invalid, or expired.
• 500 Internal Server Error on database or query failures.

Example response:

{
  "success": true,
  "data": [
    {
      "uid": "agent-1-uuid",
      "agent_name": "Billing Assistant",
      "agent_description": "Handles billing questions"
    },
    {
      "uid": "agent-2-uuid",
      "agent_name": "Tech Support",
      "agent_description": "Technical support agent"
    }
  ]
}

2. Start Agent Session from Latest Version

• Endpoint: GET /version/:uid
• Method: GET
• Description: Starts a new session using the latest available version for the agent UID.
• Authorization: Bearer token required.
• Path Parameters:
• uid (string, required): Agent UID.
• Response:
• 200 OK with created session information.
• 401 Unauthorized if authentication fails.
• 404 Not Found if no version is found for the account and agent.
• 500 Internal Server Error on query or session creation failures.

3. Start Agent Session from Specific Version Type

• Endpoint: GET /version/:uid/:version_type
• Method: GET
• Description: Starts a new session using a specific version type (for example, sandbox or live).
• Authorization: Bearer token required.
• Path Parameters:
• uid (string, required): Agent UID.
• version_type (string, required): Version type.
• Response: Same as GET /version/:uid.

4. Update Agent

• Endpoint: POST /agent
• Method: POST
• Description: Accepts agent update payloads and returns a fixed success response.
• Authorization: No explicit bearer check in code.
• Request Body:

{
  "SessionData": {
    "agent": {
      "agentId": "..."
    }
  }
}

• Response:
• 201 Created with a placeholder success response.

Example response:

{
  "success": true,
  "message": "Agent updated successfully",
  "data": "test"
}

5. Generate Token

• Endpoint: POST /token
• Method: POST
• Description: Creates an access token from client credentials.
• Content-Type: application/x-www-form-urlencoded
• Request Body Fields:
• grant_type (required): Must be client_credentials.
• client_id (required)
• client_secret (required)
• Response:
• 200 OK with token details.
• 400 Bad Request if the content type or grant type is invalid.
• 401 Unauthorized if credentials are invalid.
• 500 Internal Server Error if token generation fails.

Example response:

{
  "access_token": "...",
  "token_type": "bearer",
  "expires_in": 3600
}

6. Create or Update Session

• Endpoint: POST /session
• Method: POST
• Description: Creates or updates session data for an existing session UID.
• Authorization: Bearer token required.
• Request Body:

{
  "sessionUid": "session_uid",
  "data": {
    "...": "..."
  },
  "transferRequested": "2026-07-06T12:00:00Z",
  "transferAccepted": "2026-07-06T12:05:00Z"
}

• Notes:
• sessionUid and data are required.
• transferRequested and transferAccepted are optional RFC3339 timestamps.
• Response:
• 200 OK with updated session details.
• 400 Bad Request on invalid JSON or missing required fields.
• 401 Unauthorized if the token is invalid or expired.
• 404 Not Found if the session does not exist.
• 500 Internal Server Error if the update fails.

7. Get Session

• Endpoint: GET /session/:uid
• Method: GET
• Description: Fetches a session by UID.
• Authorization: Bearer token required.
• Path Parameters:
• uid (string, required): Session UID.
• Response:
• 200 OK with session data.
• 401 Unauthorized if authentication fails.
• 404 Not Found if the session is missing.
• 500 Internal Server Error on query failure.

8. Get Session Last Modified Timestamp

• Endpoint: GET /session/:uid/lastmodified
• Method: GET
• Description: Returns the last modified timestamp of a session.
• Authorization: Bearer token required.
• Path Parameters:
• uid (string, required): Session UID.
• Response:
• 200 OK with the timestamp.
• 404 Not Found if the session is missing.

9. Get Customer

• Endpoint: GET /customer/:value
• Method: GET
• Description: Retrieves customer details using phone, email, or UID.
• Authorization: Bearer token required.
• Path Parameters:
• value (string, required): Customer phone, email, or UID.
• Response:
• 200 OK with customer object.
• 404 Not Found if no matching customer exists.

10. Create Customer

• Endpoint: POST /customer
• Method: POST
• Description: Creates a new customer record for the authenticated account.
• Authorization: Bearer token required.
• Request Body:

{
  "phone": "1234567890",
  "email": "test@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "securepassword"
}

• Response:
• 201 Created with the created customer object.
• 400 Bad Request if the body cannot be parsed.
• 500 Internal Server Error if the customer cannot be created.

11. Update Customer

• Endpoint: POST /customer/:uid
• Method: POST
• Description: Updates an existing customer record for the authenticated account.
• Authorization: Bearer token required.
• Path Parameters:
• uid (string, required): Customer UID.
• Request Body:

{
  "customerFirst": "Jane",
  "customerLast": "Smith",
  "customerEmail": "jane@example.com",
  "customerPhone": "0987654321",
  "customerConfig": {},
  "customerData": {},
  "customerPassword": "newpassword"
}

• Response:
• 200 OK with the updated customer.
• 400 Bad Request on invalid body.
• 404 Not Found if the customer does not exist.

12. Create File Session

• Endpoint: GET /filesession/:uid
• Method: GET
• Description: Creates a new session for an agent with an empty JSON session payload.
• Authorization: Bearer token required.
• Path Parameters:
• uid (string, required): Agent UID.
• Response:
• 200 OK with created session details.
• 401 Unauthorized if token authentication fails.

13. Create File Session from Version Key

• Endpoint: POST /filesession
• Method: POST
• Description: Creates a filesession from a version key and optionally returns a bearer token.
• Request Body:

{
  "key_id": "key-id",
  "version_name": "version-name",
  "date_time": "2026-07-06T12:00:00Z",
  "payload": true,
  "key_secret": "optional-secret"
}

• Notes:
• key_secret is required for private versions.
• payload defaults to true; when true an empty session is created.
• Response:
• 200 OK with session data, generated access token, expiry, and optional key_secret.

Example response:

{
  "success": true,
  "message": "filesession created",
  "data": { ... },
  "verion_type": "live",
  "access_token": "...",
  "expires_in": 3600,
  "key_secret": null
}

14. Create Transaction

• Endpoint: POST /transaction
• Method: POST
• Description: Creates a transaction record and returns a success URL.
• Authorization: Bearer token required.
• Request Body:

{
  "transaction_form_name": "form_name",
  "transaction_variables": { "field1": "value" },
  "agent_uid_fk": "agent_uid",
  "session_uid_fk": "session_uid",
  "ttl": 2
}

• Notes:
• transaction_variables defaults to {} when omitted.
• ttl is in hours; defaults to 1 hour when omitted or non-positive.
• Response:
• 201 Created with transaction details and success_url.

Example response:

{
  "success": true,
  "message": "Transaction created successfully",
  "data": { ... },
  "success_url": "https://f.pinionai.com?f=<shortened>"
}

15. Get Transaction

• Endpoint: GET /transaction/:shortened
• Method: GET
• Description: Retrieves transaction data and form configuration by a shortened token that encodes the session UID and transaction UID.
• Path Parameters:
• shortened (string, required): Base64 URL-safe encoded session and transaction IDs.
• Response:
• 200 OK with form configuration and transaction variables.
• 400 Bad Request if the shortened token cannot be decoded.
• 404 Not Found if the transaction is missing or expired.

Example response:

{
  "success": true,
  "data": {
    "FormConfiguration": { ... },
    "TransactionVariables": { ... },
    "TransactionUid": "..."
  }
}

16. Update Transaction Status

• Endpoint: PUT /transaction/:uid
• Method: PUT
• Description: Updates a transaction's status and optional response message.
• Path Parameters:
• uid (string, required): Transaction UID.
• Request Body:

{
  "transaction_status": "completed",
  "transaction_response_message": "Success"
}

• Response:
• 200 OK with the updated transaction.
• 400 Bad Request on invalid JSON.
• 404 Not Found if the transaction does not exist.

17. Get Connector Token

• Endpoint: POST /connector
• Method: POST
• Description: Retrieves a connector access token for the authenticated account.
• Authorization: Bearer token required.
• Request Body: Either a JSON object or raw JSON string specifying the connector name.

Example object format:

{ "connector_name": "MyConnector" }

Example raw string format:

"MyConnector"

• Response:
• 200 OK with the connector token.
• 404 Not Found if the connector is missing.
• 500 Internal Server Error if token generation fails.

Example response:

{
  "success": true,
  "message": "Token retrieved successfully",
  "data": {
    "token": "Bearer ..."
  }
}

18. Get Connector Client Secret

• Endpoint: POST /vconnector
• Method: POST
• Description: Retrieves the client secret for a connector.
• Authorization: Bearer token required.
• Request Body: Same formats as /connector.
• Response:
• 200 OK with vconnector secret.
• 404 Not Found if the connector is missing.

Example response:

{
  "success": true,
  "message": "Client secret retrieved successfully",
  "data": {
    "vconnector": "secret-value"
  }
}

19. Get Database Connector Details

• Endpoint: POST /database
• Method: POST
• Description: Retrieves database connector configuration details for the authenticated account.
• Authorization: Bearer token required.
• Request Body: Same connector_name format as /connector and /vconnector.
• Response:
• 200 OK with database connector details.
• 404 Not Found if the connector is missing.

Example response:

{
  "success": true,
  "message": "Connector details fetched successfully",
  "data": {
    "connector_name": "...",
    "connector_url": "...",
    "connector_client_id": "...",
    "connector_client_secret": "...",
    "connector_port": "..."
  }
}

20. OAuth 2.0 Authorization Server Metadata

• Endpoint: GET /.well-known/oauth-authorization-server
• Method: GET
• Description: Returns RFC 8414 compliant metadata describing this server's OAuth capabilities and token endpoint. Used by automated clients for discovery.
• Authorization: No authorization required.
• Response:
• 200 OK with JSON object containing server credentials configuration.

Example response:

{
  "issuer": "https://api.example.com",
  "token_endpoint": "https://api.example.com/token",
  "token_endpoint_auth_methods_supported": ["client_secret_post"],
  "grant_types_supported": ["client_credentials"],
  "response_types_supported": []
}

21. OAuth 2.0 Protected Resource Metadata

• Endpoint: GET /.well-known/oauth-protected-resource
• Method: GET
• Description: Returns RFC 9728 compliant metadata linking this API (protected resource) to its matching Authorization Server (itself) to facilitate automated dynamic token discovery.
• Authorization: No authorization required.
• Response:
• 200 OK with JSON metadata linking back to authorization resources.

Example response:

{
  "resource": "https://api.example.com",
  "authorization_servers": ["https://api.example.com"],
  "scopes_supported": ["api"],
  "bearer_methods_supported": ["header"]
}

22. MCP SSE Connection Endpoint

• Endpoint: GET /mcp/sse
• Method: GET
• Description: Establishes a persistent Server-Sent Events (SSE) connection to access Model Context Protocol (MCP) server capabilities. Upon connecting, the server immediately pushes an endpoint event containing a relative message posting URI with an assigned sessionId for this client stream.
• Authorization: Bearer token required (accepted via Authorization: Bearer <token> header OR query parameter ?token=<token>).
• Response:
• 200 OK with Content-Type: text/event-stream and chunked transfer.
• 401 Unauthorized if no valid token is provided or has expired.

Example handshake event pushed by server:

event: endpoint
data: /mcp/message?sessionId=1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

23. MCP Message Processor Endpoint

• Endpoint: POST /mcp/message
• Method: POST
• Description: Post endpoint for sending JSON-RPC 2.0 requests to the active MCP session. The request body is processed asynchronously and any resulting JSON-RPC response or error frame is returned via the corresponding SSE channel stream established on /mcp/sse.
• Query Parameters:
• sessionId (string, required): The active session UUID returned by the initial /mcp/sse endpoint handshake event.
• Request Body: Standard JSON-RPC 2.0 Request Object.
• Responses:
• 202 Accepted indicating the message is successfully enqueued for processing.
• 400 Bad Request on invalid formatting.
• 404 Not Found if the session ID is missing or has expired.

Exposed MCP Tools

Under MCP capabilities, the API exposes the following executable tool:

create_transaction

• Description: Create a new transaction record for a form. Returns transaction details and a success URL.
• Arguments JSON Schema:

  {
    "type": "object",
    "properties": {
      "transaction_form_name": {
        "type": "string",
        "description": "The name of the form associated with the transaction."
      },
      "transaction_variables": {
        "type": "object",
        "description": "JSON object containing form variables (key-value pairs)."
      },
      "agent_uid_fk": {
        "type": "string",
        "description": "The unique identifier of the agent."
      },
      "session_uid_fk": {
        "type": "string",
        "description": "The unique identifier of the session (optional, generated if omitted)."
      },
      "ttl": {
        "type": "integer",
        "description": "Time to live in hours (optional, defaults to 1)."
      }
    },
    "required": ["transaction_form_name", "agent_uid_fk"]
  }
  

get_form_fields

• Description: Retrieve form fields for a given form name.
• Arguments JSON Schema:

  {
    "type": "object",
    "properties": {
      "form_name": {
        "type": "string",
        "description": "The name of the form to retrieve fields for."
      }
    },
    "required": ["form_name"]
  }
  

get_transaction_status

• Description: Retrieve transaction status and response message for a specific transaction.
• Arguments JSON Schema:

  {
    "type": "object",
    "properties": {
      "transactionUid": {
        "type": "string",
        "description": "The unique identifier of the transaction."
      }
    },
    "required": ["transactionUid"]
  }
  

24. Form Fields Endpoint

• Endpoint: POST /formname
• Method: POST
• Description: Retrieve form fields from the forms table for a given form name.
• Authorization: Bearer token required (accepted via Authorization: Bearer <token> header OR query parameter ?token=<token>).
• Request Body:

  {
    "form_name": "name and email"
  }
  

• Responses:
• 200 OK with JSON payload containing the form name and fields.

  {
    "form_name": "name and email",
    "form_fields": ["firstName", "lastName", "email"]
  }
  

• 400 Bad Request if form_name is missing or invalid.
• 401 Unauthorized if token is missing, invalid, or expired.
• 404 Not Found if the form does not exist.

25. Modern MCP Endpoint

• Endpoint: POST /mcp
• Method: POST
• Description: Modern, stateless Model Context Protocol (MCP) Streamable HTTP endpoint. Processes incoming JSON-RPC 2.0 requests synchronously.
• Authorization: Bearer token required (accepted via Authorization: Bearer <token> header OR query parameter ?token=<token>).
• Headers:
• MCP-Protocol-Version (string, required): Must equal "2026-07-28" (or legacy "2024-11-05").
• Mcp-Method (string, required): Mirrors the JSON-RPC body method.
• Mcp-Name (string, optional): Required for tools/call, mirroring the tool name (e.g. "create_transaction", "get_form_fields", or "get_transaction_status").
• Request Body: Standard JSON-RPC 2.0 Request Object.
• Responses:
• 200 OK with standard JSON-RPC 2.0 Response Object in the body (application/json).
• 400 Bad Request with code -32020 on header mismatch or missing headers.
• 401 Unauthorized if token is missing or invalid.
• 403 Forbidden if the Origin header is present but invalid.
• 404 Not Found with code -32601 if the method or tool is unknown.

26. Transaction Status Endpoint

• Endpoint: POST /status
• Method: POST
• Description: Retrieve transaction status and response message for a specific transaction.
• Authorization: Bearer token required (accepted via Authorization: Bearer <token> header OR query parameter ?token=<token>).
• Request Body:

  {
    "transactionUid": "04369177-ff13-42b0-8dc3-a3ec5288b0c8"
  }
  

• Responses:
• 200 OK with JSON payload containing the transaction status and optional response message.

  {
    "transaction_status": "created",
    "transaction_response_message": "Success"
  }
  

• 400 Bad Request if transactionUid is missing or invalid.
• 401 Unauthorized if token is missing, invalid, or expired.
• 404 Not Found if the transaction does not exist.

---

Data Structures

pathParameters

type pathParameters struct {
    UID string `uri:"uid" binding:"required"`
}

customerParameters

type customerParameters struct {
    Value string `uri:"value" binding:"required"`
}

Token endpoint form fields

The /token endpoint requires application/x-www-form-urlencoded input with the following fields:

• grant_type: must be client_credentials
• client_id
• client_secret

CreateCustomerRequest

type CreateCustomerRequest struct {
    Phone     string `json:"phone"`
    Email     string `json:"email"`
    FirstName string `json:"firstName"`
    LastName  string `json:"lastName"`
    Password  string `json:"password"`
}

CreateTransactionRequest

type CreateTransactionRequest struct {
    TransactionFormName  string          `json:"transaction_form_name" binding:"required"`
    TransactionVariables json.RawMessage `json:"transaction_variables"`
    AgentUidFk           string          `json:"agent_uid_fk" binding:"required"`
    SessionUidFk         string          `json:"session_uid_fk" binding:"required"`
    TTL                  int             `json:"ttl"`
}

UpdateTransactionStatusRequest

type UpdateTransactionStatusRequest struct {
    TransactionStatus          string `json:"transaction_status" binding:"required"`
    TransactionResponseMessage string `json:"transaction_response_message"`
}

GetTransactionStatusRequest

type GetTransactionStatusRequest struct {
    TransactionUid string `json:"transactionUid" binding:"required"`
}

ConnectorRequest

type ConnectorRequest struct {
    ConnectorName string `json:"connector_name" binding:"required"`
}

TokenResponse

type TokenResponse struct {
    AccessToken string `json:"access_token"`
    TokenType   string `json:"token_type"`
    ExpiresIn   int64  `json:"expires_in"`
}

Token

type Token struct {
    ID           int64     `json:"id"`
    AccountUidFk string    `json:"account_uid_fk"`
    TokenType    int32     `json:"token_type"`
    Token        string    `json:"token"`
    Expiry       time.Time `json:"expiry"`
    Lastmodified time.Time `json:"lastmodified"`
}

---

Notes

• The POST /agent endpoint is currently implemented as a placeholder and does not perform a real update.
• POST /session expects data as a JSON object and requires sessionUid.
• POST /filesession may return a generated bearer token and access to a version-based session.
• /transaction/:shortened decodes a combined session and transaction UID using a URL-safe Base64 format.
• Most endpoints that require authentication use Bearer token validation with expiry checking.
• CORS is enabled for all origins by default (should be restricted for production use).