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>

Endpoints

1. Start Agent Session

  • Endpoint: GET /agent/:uid
  • Method: GET
  • Description: Initiates an agent session. It retrieves agent information based on the provided UID and creates a new session.
  • Authorization: Bearer token required.
  • Path Parameters:
  • uid (string, required): The unique identifier of the agent.
  • Responses:
  • 200 OK: Agent started successfully. 
    {
  "success": true,
  "message": "Agent started successfully",
  "data": {
    // Session object
    "uid": "session_uid",
    "customer_uid_fk": null,
    "agent_uid_fk": "agent_id_from_agent_json",
    "account_uid_fk": "account_id_from_token",
    "session_data": {
      /* agent JSON data */
    },
    "created": "timestamp",
    "lastmodified": "timestamp",
    "transfer_requested": null,
    "transfer_accepted": null
  }
}
  • 400 Bad Request: Invalid UID format. 
    {
  "parse error": "message"
}
  • 401 Unauthorized: Missing or invalid bearer token, or token expired. 
    {
  "error": "Invalid or missing Authorization header. Expected 'Bearer <token>'." // or "Invalid token" or "Token expired"
}
  • 404 Not Found: Agent not found. 
    {
  "agent error": "sql: no rows in result set"
}
  • 500 Internal Server Error: Database or other server error. 
    {
  "error": "Database error" // or "Failed to parse agent data" or "session error": "message"
}

2. Start Agent Session from Version

  • Endpoint:
  • GET /version/:uid
  • GET /version/:uid/:version_type
  • Method: GET
  • Description: Initiates an agent session based on a specific version. It retrieves agent version data and creates a new session.
  • Authorization: Bearer token required.
  • Path Parameters:
  • uid (string, required): The unique identifier of the agent.
  • version_type (string, optional): The type of the version (e.g., "sandbox", "live"). Defaults to "live" if not provided (handled by the backend SQL query).
  • Responses:
  • 200 OK: Agent version started successfully. 
    {
  "success": true,
  "message": "Agent version started successfully",
  "data": {
    // Session object
    "uid": "session_uid",
    "customer_uid_fk": null,
    "agent_uid_fk": "agent_uid_from_path", // or extracted from version data
    "account_uid_fk": "account_id_from_token",
    "session_data": {
      /* agent version data */
    },
    "created": "timestamp",
    "lastmodified": "timestamp",
    "transfer_requested": null,
    "transfer_accepted": null
  }
}
  • 400 Bad Request: Invalid UID format.
  • 401 Unauthorized: Missing or invalid bearer token, or token expired.
  • 404 Not Found: Agent version not found.
  • 500 Internal Server Error: Database or other server error.

3. Generate Token

  • Endpoint: POST /token
  • Method: POST
  • Description: Generates a new access token for a client.
  • Request Body: 
    {
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}
  • Responses:
  • 200 OK: Token generated successfully. 
    {
  "access_token": "generated_token_string",
  "token_type": "bearer",
  "expires_in": 3600 // seconds until expiry
}
  • 400 Bad Request: Invalid request format or unsupported grant type.
  • 401 Unauthorized: Invalid client credentials.
  • 500 Internal Server Error: Database or other server error.

4. Create or Update Session

  • Endpoint: POST /session
  • Method: POST
  • Description: Creates or updates an agent session. sessionUid can be provided in URL query, form data, or JSON body.
  • Authorization: Bearer token required.
  • Request Body (if sessionUid and data in JSON): 
    {
  "sessionUid": "existing_or_new_session_uid",
  "data": {
    /* session data to update */
  },
  "transferRequested": "YYYY-MM-DDTHH:MM:SSZ", // Optional RFC3339 timestamp
  "transferAccepted": "YYYY-MM-DDTHH:MM:SSZ" // Optional RFC3339 timestamp
}
  • Query/Form Parameters (alternative to JSON body for sessionUid):
  • sessionUid (string)
  • Responses:
  • 200 OK: Session data updated successfully. 
    {
  "success": true,
  "message": "Session data updated",
  "data": {
    /* updated session object */
  }
}
  • 400 Bad Request: Invalid request format (e.g., missing sessionUid, invalid timestamp format).
  • 401 Unauthorized: Missing or invalid bearer token, or token expired.
  • 404 Not Found: Session not found (if updating an existing session).
  • 500 Internal Server Error: Database or other server error.

5. Get Session

  • Endpoint: GET /session/:uid
  • Method: GET
  • Description: Retrieves an agent session.
  • Authorization: Bearer token required.
  • Path Parameters:
  • uid (string, required): The unique identifier of the session.
  • Responses:
  • 200 OK: Session retrieved successfully. 
    {
  "success": true,
  "data": {
    /* session object */
  }
}
  • 400 Bad Request: Invalid UID format.
  • 401 Unauthorized: Missing or invalid bearer token, or token expired.
  • 404 Not Found: Session not found.
  • 500 Internal Server Error: Database or other server error.

6. Get Session Last Modified Timestamp

  • Endpoint: GET /session/:uid/lastmodified
  • Method: GET
  • Description: Retrieves the last modified timestamp for a given session UID.
  • Authorization: Bearer token required.
  • Path Parameters:
  • uid (string, required): The unique identifier of the session.
  • Responses:
  • 200 OK: Last modified timestamp retrieved successfully. 
    {
  "success": true,
  "data": "YYYY-MM-DDTHH:MM:SS.ssssssZ" // or relevant timestamp format from DB
}
  • 400 Bad Request: Invalid UID format.
  • 401 Unauthorized: Missing or invalid bearer token, or token expired.
  • 404 Not Found: Session not found.
  • 500 Internal Server Error: Database or other server error.

7. Get Customer

  • Endpoint: GET /customer/:value
  • Method: GET
  • Description: Retrieves customer data by phone, email, or UID, associated with the authenticated account.
  • Authorization: Bearer token required.
  • Path Parameters:
  • value (string, required): The customer's phone number, email address, or unique identifier.
  • Responses:
  • 200 OK: Customer data retrieved successfully. 
    {
  "success": true,
  "data": {
    /* customer object */
  }
}
  • 400 Bad Request: Invalid value format.
  • 401 Unauthorized: Missing or invalid bearer token, or token expired.
  • 404 Not Found: Customer not found.
  • 500 Internal Server Error: Database or other server error.

8. Create Customer

  • Endpoint: POST /customer
  • Method: POST
  • Description: Creates a new customer associated with the authenticated account.
  • Authorization: Bearer token required.
  • Request Body: 
    {
  "phone": "1234567890",
  "email": "test@example.com",
  "firstName": "John",
  "lastName": "Doe"
}
  • Responses:
  • 201 Created: Customer created successfully. 
    {
  "success": true,
  "data": {
    /* created customer object */
  }
}
  • 400 Bad Request: Invalid request format.
  • 401 Unauthorized: Missing or invalid bearer token, or token expired.
  • 500 Internal Server Error: Database or other server error.

9. Update Customer

  • Endpoint: POST /customer/:uid
  • Method: POST
  • Description: Updates an existing customer associated with the authenticated account. Fields not provided in the request will retain their existing values.
  • Authorization: Bearer token required.
  • Path Parameters:
  • uid (string, required): The unique identifier of the customer to update.
  • Request Body (all fields optional, provide only what needs to be updated): 
    {
  "customerFirst": "UpdatedFirstName",
  "customerLast": "UpdatedLastName",
  "customerEmail": "updated@example.com",
  "customerPhone": "0987654321",
  "customerConfig": {
    /* new JSON config object */
  },
  "customerData": {
    /* new JSON data object */
  }
}
    Note: The database.UpdateCustomerParams struct is used for binding, so field names in the JSON should match the json tags in that struct (e.g., customerFirst, customerLast, customerEmail, customerPhone, customerConfig, customerData).
  • Responses:
  • 200 OK: Customer updated successfully. 
    {
  "success": true,
  "data": {
    /* updated customer object */
  }
}
  • 400 Bad Request: Invalid request format or missing UID.
  • 401 Unauthorized: Missing or invalid bearer token, token expired.
  • 404 Not Found: Customer not found.
  • 500 Internal Server Error: Database or other server error.

Data Structures

pathParameters

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

customerParameters

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

TokenRequest

type TokenRequest struct {
    GrantType    string `json:"grant_type"`
    ClientID     string `json:"client_id"`
    ClientSecret string `json:"client_secret"`
}

CreateCustomerRequest

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

(Other internal or database-specific structs like apiAgent, TokenResponse, Token, database.CreateSessionParams, database.UpdateCustomerParams etc., are used internally but their relevant fields are reflected in the request/response examples above.)