Skill Execution

The skill execution endpoint is the primary way to trigger agent skills programmatically. Each skill is exposed through a category-versioned URL pattern, and execution is asynchronous by default.

---

Execute a Skill

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

Execute a skill by its category, version, and name. The request is queued for asynchronous processing.

Requires authentication via x-api-key header.

URL Structure

The endpoint follows a consistent pattern:

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

Segment	Description	Examples
category	The integration or skill category.	quickbooks, sage-intacct, web, platform
version	The skill version.	v1, v2
skill-name	The specific skill to execute (kebab-case).	profit-and-loss-report, query-customer, create-site

Full example paths:

• POST /api/quickbooks/v1/profit-and-loss-report
• POST /api/sage-intacct/v1/query-gldetail
• POST /api/web/v1/create-site
• POST /api/platform/v1/get-skill

Authentication and Scopes

Skill execution requires an API key (x-api-key header) with a scope matching the skill’s category. For example, calling a QuickBooks skill requires the quickbooks scope.

If the API key lacks the required scope, the API returns a 403 Forbidden error:

{
  "error": "insufficient_scope",
  "message": "The API key does not have the required scope 'quickbooks' for this operation."
}

Request Body

The request body is specific to each skill. Refer to the individual skill reference pages in the Skill Reference section for the exact parameters each skill accepts.

Request Example

curl -X POST https://api.horizonplatform.ai/api/quickbooks/v1/profit-and-loss-report \
  -H "x-api-key: hz_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2026-01-01",
    "end_date": "2026-03-31",
    "accounting_method": "Accrual"
  }'

const response = await fetch(
  'https://api.horizonplatform.ai/api/quickbooks/v1/profit-and-loss-report',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'hz_live_abc123def456',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      start_date: '2026-01-01',
      end_date: '2026-03-31',
      accounting_method: 'Accrual',
    }),
  }
);

const result = await response.json();
console.log(result.job_id); // Use this to track execution

import requests

response = requests.post(
    'https://api.horizonplatform.ai/api/quickbooks/v1/profit-and-loss-report',
    headers={
        'x-api-key': 'hz_live_abc123def456',
        'Content-Type': 'application/json',
    },
    json={
        'start_date': '2026-01-01',
        'end_date': '2026-03-31',
        'accounting_method': 'Accrual',
    }
)

result = response.json()
print(result['job_id'])  # Use this to track execution

Response

Skill execution is asynchronous. The API immediately returns a 202 Accepted response confirming the skill has been queued:

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

Response Fields

Parameter	Type	Description
status required	string	Always 'accepted' for successful submissions.
message required	string	Confirmation message.
job_id required	string	Unique identifier for tracking the queued job.

Async Processing Model

When a skill execution request is accepted, the following happens:

1. Validation — The API validates the request body, API key, and scope.
2. Queueing — The skill execution job is added to a BullMQ queue.
3. Processing — A worker picks up the job, invokes the appropriate agent, and executes the skill against the connected service.
4. Completion — Results are stored and accessible via the Conversations endpoints.

This asynchronous model ensures that:

• Your API calls return quickly regardless of how long the skill takes to execute.
• Long-running operations (such as large report generation) do not time out.
• The platform can manage concurrency and retry failed executions automatically.

Tracking Execution Results

Since execution is async, you have several options for retrieving results:

1. Poll the Conversations API

After submitting a skill execution, the agent creates a conversation. Use the Conversations endpoints to check the status and retrieve results:

curl -X GET https://api.horizonplatform.ai/api/conversations \
  -H "x-api-key: hz_live_abc123def456"

const conversations = await fetch(
  'https://api.horizonplatform.ai/api/conversations',
  { headers: { 'x-api-key': 'hz_live_abc123def456' } }
).then(r => r.json());

import requests

conversations = requests.get(
    'https://api.horizonplatform.ai/api/conversations',
    headers={'x-api-key': 'hz_live_abc123def456'}
).json()

2. Use Webhook Callbacks

Configure a webhook with a callback_url to receive results via HTTP POST when execution completes. This is ideal for event-driven architectures.

3. Synchronous Webhook Triggers

For cases where you need an immediate result, use the webhook trigger endpoint with synchronous: true. This blocks until the agent completes and returns the result inline.

Tip

For production integrations, webhook callbacks are the most efficient approach. They eliminate polling overhead and deliver results as soon as they are available.

Error Responses

Status	Error	Description
400	validation_error	Invalid request body or missing required skill parameters.
401	authentication_required	Missing or invalid API key.
403	insufficient_scope	API key lacks the scope required for this skill category.
404	skill_not_found	The specified category, version, or skill name does not exist.
429	rate_limit_exceeded	API key rate limit exceeded.