API Access

Here you can see our API endpoints live documentation.

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). Check out the Streaming Events guide for more information about the specific events you can expect.

• 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[]
}

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:

• Messages follow the PromptL format. If you’re using a different method to run your prompts, you’ll need to format your messages accordingly.

{
  "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. Check out the Streaming Events guide for more information about the specific events you can expect.

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.

Check out the Streaming Events guide for more information about the specific events you can expect.

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:

• Messages follow the PromptL format. If you’re using a different method to run your prompts, you’ll need to format your messages accordingly.

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