API Access

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

Rate Limiting

The API enforces rate limits based on your API key to ensure fair usage and prevent abuse.

Limits:

Rate Limit Points: 1000 requests
Rate Limit Duration: 60 seconds

When the rate limit is exceeded, the following headers are included in the response to help you manage your request rate:

Retry-After: Indicates the number of seconds to wait before making a new request.
X-RateLimit-Limit: The maximum number of requests allowed in the current period.
X-RateLimit-Remaining: The number of requests remaining in the current period.
X-RateLimit-Reset: The timestamp when the rate limit will reset.

Example Headers:

Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1729399082482

These headers are sent with every request to help you monitor and adjust your request rate accordingly.

Endpoints

1. Get a Document

Retrieve a specific prompt by its path.

Endpoint: GET /projects/{projectId}/versions/{versionUuid}/documents/{path}

Path Parameters:

projectId: Your project ID (required)
versionUuid: Version UUID (required, optional for SDK’s defaults to ‘live’)
path: Path to the document (required)

Response:

The response contains the existing document details along with its configuration.

Response Body:

{
  "id": "document-id",
  "documentUuid": "document-uuid",
  "path": "path/to/document",
  "content": "Document content",
  "resolvedContent": "Document content without comments",
  "contentHash": "content-hash",
  "commitId": "commit-id",
  "deletedAt": "deleted-at",
  "createdAt": "created-at",
  "updatedAt": "updated-at",
  "mergedAt": "merged-at",
  "projectId": "project-id",
  "config": {
    "provider": "Provider name",
    "model": "Model name"
  }
}

2. Get or Create a Document

Endpoint: POST /projects/{projectId}/versions/{versionUuid}/documents/get-or-create

Path Parameters:

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

Request Body:

{
  "path": "path/to/document",
  "prompt": "Your prompt here"
}

path: Path to the document (required)
prompt: Prompt to use for the document (optional, defaults to empty)

Response:

The response contains the created (or existing) document details along with its configuration.

Response Body:

{
  "id": "document-id",
  "documentUuid": "document-uuid",
  "path": "path/to/document",
  "content": "Document content",
  "resolvedContent": "Document content without comments",
  "contentHash": "content-hash",
  "commitId": "commit-id",
  "deletedAt": "deleted-at",
  "createdAt": "created-at",
  "updatedAt": "updated-at",
  "mergedAt": "merged-at",
  "projectId": "project-id",
  "config": {
    "provider": "Provider name",
    "model": "Model name"
  }
}

3. 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 (required, optional for SDK’s defaults to ‘live’)

Request Body:

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

stream: Optional boolean parameter (defaults to false). When set to true, the response will be a stream of Server-Sent Events (SSE). If false, a single JSON response containing the last event is returned.

Response:

If stream is true: 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": Message[],
  "response": {
    "text": string,
    "toolCalls": ToolCall[],
    "usage": {
      "promptTokens": number,
      "completionTokens": number,
      "totalTokens": number
    }
  }
}

If stream is false: A single JSON response is returned with the final event (typically the chain-complete event) in the following structure:

{
  "uuid": string,
  "conversation": Message[],
  "response": {
    "streamType": "text" | "object",
    "usage": {
      "promptTokens": number,
      "completionTokens": number,
      "totalTokens": number
    },
    "text": string,
    "object": object | undefined,
    "toolCalls": ToolCall[]
}

Message follows OpenAI’s format.

ToolCall has the following format:

type ToolCall = {
  id: string
  name: string
  arguments: Record<string, unknown>
}

4. 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:

follows OpenAI’s format or the vercel’s ai sdk

{
  "messages": [
    {
      "role": "user" | "system" | "assistant",
        {
          "type": "text",
          "content": string
        }
    }
  ],
  "stream": true
}

stream: Optional boolean parameter (defaults to false). When set to true, the response will be a stream of Server-Sent Events (SSE). If false, a single JSON response containing the last event is returned.

Message follows OpenAI’s format.

Response: The response is a stream of Server-Sent Events (SSE) or a single JSON response containing the final event, 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:

Set up an EventSource or use a library that supports SSE.
Listen for events and parse the JSON data in each event.
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"
  }
}

5. Evaluate a Conversation

Evaluate a conversation using configured evaluations.

Endpoint: POST /conversations/{conversationUuid}/evaluate

Path Parameters:

conversationUuid: UUID of the conversation to evaluate

Request Body:

{
  "evaluationUuids": ["evaluation-uuid-1", "evaluation-uuid-2"] // optional, defaults to all evaluations connected to the conversation prompt
}

Response:

{
  "evaluations": ["evaluation-uuid-1", "evaluation-uuid-2"] // array of evaluation UUIDs that will be run
}

6. Create Log Entry

Create a log entry for a document.

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

Path Parameters:

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

Request Body:

follows OpenAI’s format or the vercel’s ai sdk

{
  "path": "path/to/document",
  "messages": [
    {
      "role": "user" | "system" | "assistant",
        {
          "type": "text",
          "content": string
        }
    }
  ],
  "response": string
}

Response:

{
  "id": "document-id",
  "uuid": "log-uuid",
  "documentUuid": "document-uuid",
  "commitId": "commit-id",
  "resolvedContent": "Document content without comments",
  "contentHash": "content-hash",
  "parameters": {},
  "customIdentifier": "custom-identifier",
  "duration": "duration",
  "source": "source",
  "createdAt": "created-at",
  "updatedAt": "updated-at"
}

7. Create Evaluation Result

Create an evaluation result for a conversation using a configured evaluation.

Endpoint: POST /conversations/{conversationUuid}/evaluations/{evaluationUuid}/results

Path Parameters:

conversationUuid: UUID of the conversation to evaluate
evaluationUuid: UUID of the evaluation to use

Request Body:

{
  "result": 2,
  "reason": "The output is not relevant to the prompt"
}

Response:

{
  "id": "evaluation-result-id",
  "result": 2,
  "reason": "The output is not relevant to the prompt",
  "createdAt": "created-at",
  "updatedAt": "updated-at"
}

Getting started

Prompt Manager

Evaluations

Logs

Datasets

HTTP API

SDKs

Cookbook

Self-hosting

Latitude HTTP API Documentation

Authentication

Base URL

Rate Limiting

Endpoints

1. Get a Document

2. Get or Create a Document

3. Run a Document

4. Chat

Handling Server-Sent Events (SSE)

Error Handling

5. Evaluate a Conversation

6. Create Log Entry

7. Create Evaluation Result

Getting started

Prompt Manager

Evaluations

Logs

Datasets

HTTP API

SDKs

Cookbook

Self-hosting

​Latitude HTTP API Documentation

​Authentication

​Base URL

​Rate Limiting

​Endpoints

​1. Get a Document

​2. Get or Create a Document

​3. Run a Document

​4. Chat

Handling Server-Sent Events (SSE)

Error Handling

​5. Evaluate a Conversation

​6. Create Log Entry

​7. Create Evaluation Result

Latitude HTTP API Documentation

Authentication

Base URL

Rate Limiting

Endpoints

1. Get a Document

2. Get or Create a Document

3. Run a Document

4. Chat

5. Evaluate a Conversation

6. Create Log Entry

7. Create Evaluation Result