Skip to content

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 /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

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": "..."
  }
}

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": "..."
  }
}

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"`
}

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).