API Overview

The Horizon API gives you programmatic access to every capability of the platform. You can execute skills, manage conversations, read and write agent memory, schedule recurring jobs, and configure webhooks, all through standard HTTP requests.

Base URL

All API requests are made to your Horizon instance’s base URL:

https://api.horizonplatform.ai

Admin endpoints are prefixed with /admin, while standard API endpoints use the /api prefix. Webhook trigger endpoints are publicly accessible at their token-based URLs.

Versioning

Skill execution endpoints include an explicit version in the path:

POST /api/{category}/{version}/{skill-name}

For example, /api/quickbooks/v1/profit-and-loss-report. All other API endpoints are unversioned and follow a stable contract. Breaking changes are communicated through the Release Notes and will always include a migration period.

Request Format

All request bodies must be sent as JSON with the Content-Type: application/json header. Query parameters are used for filtering and pagination on GET requests.

POST /api/quickbooks/v1/profit-and-loss-report HTTP/1.1
Host: api.horizonplatform.ai
Content-Type: application/json
x-api-key: hz_live_abc123...

{
  "start_date": "2026-01-01",
  "end_date": "2026-03-31"
}

Response Format

All responses return JSON. Successful responses include the relevant data directly in the response body. Error responses follow a consistent structure described in the Errors reference.

A typical successful response:

{
  "id": "conv_8f3a2b1c",
  "agent_id": "agent_001",
  "status": "completed",
  "created_at": "2026-03-18T14:30:00Z"
}

List endpoints return arrays, often with pagination metadata:

[
  { "id": "job_001", "name": "Weekly P&L", "status": "active" },
  { "id": "job_002", "name": "Daily Sync", "status": "active" }
]

Asynchronous Execution Model

Skill execution in Horizon is asynchronous by default. When you submit a skill execution request, the API returns a 202 Accepted response immediately. The actual work is queued via BullMQ and processed by the appropriate agent in the background.

{
  "status": "accepted",
  "message": "Skill execution queued",
  "job_id": "job_9f8e7d6c"
}

This design ensures that long-running operations (such as pulling large financial reports or performing multi-step workflows) do not block your API calls. You can track the progress and results through the Conversations endpoints.

Webhook triggers also support both synchronous and asynchronous modes. Pass synchronous: true in the webhook trigger body to wait for the result inline. See Webhooks for details.

Tip

For time-sensitive integrations that need immediate results, use the synchronous webhook trigger mode or poll the conversation endpoint after skill execution.

Pagination

List endpoints support limit and offset query parameters for pagination. Each endpoint documents its default and maximum values:

Endpoint	Default Limit	Max Limit
Conversations	50	200
Messages	100	500
Scheduled Jobs	50	—
Memories	50	—

Authentication

Horizon uses two authentication mechanisms depending on the endpoint:

• API keys (x-api-key header) for standard API operations. Keys are scoped to specific skill categories.
• Admin secret (Authorization: Bearer {admin_secret} or x-admin-secret header) for administrative operations like managing API keys.

See the Authentication page for full details.

Quick Reference

Authentication API keys, admin secrets, scopes, and key rotation.

Skill Execution Execute any skill via the REST API.

Conversations List, retrieve, and inspect conversation history.

Agent Memory Read and write agent memory programmatically.

Scheduled Jobs Create and manage recurring agent tasks.

Webhooks Configure inbound webhooks and trigger agents externally.