We recommend checking the SDK docs section in case you’re looking for a specific language or framework.

Latitude HTTP API Documentation

This guide explains how to use the Latitude HTTP API to interact with the Prompt Manager and run AI-powered conversations.

Authentication

All API requests require authentication. Include your API key in the Authorization header of your HTTP requests:

Authorization: Bearer YOUR_API_KEY

Base URL

The base URL for API requests depends on your environment:

https://gateway.latitude.so/api/v1

Endpoints

1. Run a Document

Run a specific document (prompt) with optional parameters.

Endpoint: POST /projects/{projectId}/versions/{versionUuid}/documents/run

Path Parameters:

  • projectId: Your project ID (required)
  • versionUuid: Version UUID (optional, defaults to ‘live’)

Request Body:

{
  "path": "path/to/document",
  "parameters": {
    "key1": "value1",
    "key2": "value2"
  }
}

Response: The response is a stream of Server-Sent Events (SSE). Each event contains JSON data with the following structure:

{
  "type": "chain-step" | "chain-step-complete" | "chain-complete",
  "isLastStep": boolean,
  "uuid": string,
  "config": {
    "provider": string,
    "model": string
  },
  "messages": [
    {
      "role": "system" | "user" | "assistant",
      "content": string,
      "toolCalls": []
    }
  ],
  "response": {
    "text": string,
    "toolCalls": [],
    "usage": {
      "promptTokens": number,
      "completionTokens": number,
      "totalTokens": number
    }
  }
}

2. Chat

The previously described POST /projects/{projectId}/versions/{versionUuid}/documents/run endpoint can also be used to continue a conversation. Notice all events contain a uuid field that represents that conversation with the AI. You can use this uuid to continue the conversation.

Endpoint: POST /conversations/{conversationUuid}/chat

Path Parameters:

  • conversationUuid: UUID of the conversation

Request Body:

{
  "messages": [
    {
      "role": "user" | "system" | "assistant",
      "content": string
    }
  ]
}

Response: The response is a stream of Server-Sent Events (SSE), similar to the “Run a Document” endpoint.

Handling Server-Sent Events (SSE)

The API uses SSE for real-time updates. Here’s how to handle SSE responses:

  1. Set up an EventSource or use a library that supports SSE.
  2. Listen for events and parse the JSON data in each event.
  3. Handle different event types:
    • latitude-event: Contains information about the chain progress and results.
    • provider-event: Contains real-time updates from the AI provider.

Error Handling

The API uses standard HTTP status codes. In case of an error, the response body will contain an error message:

{
  "error": {
    "message": "Error description"
  }
}