App API

The programmatic surface of the Horizon API, /api/v2/agent/*, called with an hzn_ API key. Which /api/v2 routes a key can reach, how each request is authorized, and every endpoint with its body, response and status codes.

https://api.horizonplatform.ai/api/v2/agent/* is the part of the Horizon API built for programs that hold an hzn_ API key: boards, tasks, labels, organization members and Sales records.

Your own integrations call it with a key you create in Settings (see API Key Management). Horizon’s own agents call the same routes, through skills that hold an hzn_ key.

Which routes an API key can reach

An Authorization: Bearer hzn_... key reaches three groups of /api/v2 routes, and no others:

The paths closed to keys by that last rule include /settings, /org, /billing, /connections, /agents, /apps, /skills, /modules, /services, /onboarding, /dashboard, /notifications, /operator, /connector-actions and /marketing/sites, apart from four organization-setup routes under /org, /billing and /settings that have module features of their own (see Organization setup with a key). A set of named finance actions is closed as well, among them /erp/finance/disbursement-freeze and /erp/finance/remittance. Because the API keys routes under /settings are closed, a key cannot create, list or revoke keys. An owner or admin creates them in the dashboard, and each key is hzn_ followed by 32 random bytes in base64url.

The refusal says why the path is closed in details.reason, and details.path is the path relative to /api/v2:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "API keys cannot access this endpoint",
    "details": {
      "path": "/erp/finance/customers",
      "reason": "retired",
      "movedTo": ["/api/v2/forms/customers"],
      "hint": "This path belonged to the retired legacy finance API. For customers, use /api/v2/forms/customers."
    }
  }
}

A path under /api/v2/agent/ that matches none of the endpoints on this page is refused the same way, with details.reason no_route. The exception is paths under /api/v2/agent/users, which are checked against the key’s system.users permission for the request’s method: a key that holds it gets the 404 below instead.

A request that a key may make, or any request from a signed-in session, to a path where no route exists gets 404 in the same envelope:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No API route matches GET /api/v2/tasks",
    "details": {
      "method": "GET",
      "path": "/api/v2/tasks",
      "reason": "no_collection_root",
      "movedTo": [
        "/api/v2/my-tasks",
        "/api/v2/boards/:boardId/tasks"
      ],
      "hint": "…"
    }
  }
}

details.reason is no_collection_root for a path that serves only records below it, retired for a path that belonged to a retired API, and otherwise no_route. movedTo and hint are present when Horizon knows where to go instead. On /api/v2/forms/*, an unknown entity type is a 404 in problem-details form instead, with "detail": "Unknown entity type".

The retired finance endpoints a key can still reach, under /api/v2/erp/finance/bank and /api/v2/erp/finance/periods, answer 501 with code NOT_IMPLEMENTED in the same envelope, and details.movedTo where there is a replacement.

Same key, two enforcement paths

The /api/v2/agent/* routes and the module routes accept the same key and read the same permissions. What they check differs:

Authentication and authorization

Every /api/v2/agent/* request is first counted against the key’s rate limit, then checked in this order: the key, who the request acts as (see Actor), the key’s creator and the active legal entity, then the one permission the route needs.

Request headers

Key checks

Horizon looks the key up by its hash. It must exist and be active:

The key’s creator must be an active member of the key’s organization:

These two refusals apply on every /api/v2/agent/* route, and on every other route a key can reach, whatever the organization’s Multi-entity separation setting: Off, Standard, Strict or Inherit.

Removing or deactivating the creator does not revoke the key. It stays active, and it works again from its next request if the creator is reactivated or rejoins the organization. To stop a key for good, revoke or delete it.

Rate limits

Each key can make 1,000 requests to /api/v2/agent/* per 60-second window. Over that, a request is refused with 429:

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests" } }

• Counted per key. Each key has its own count. Two keys in the same organization do not share one, and calls Horizon’s own agents make with a key count against that key like any other.
• Counted before the key is checked. A request that is then refused, for example with 401 or 403, still counts.
• Separate from the other routes. The other /api/v2 routes a key can reach allow 100 requests per 60 seconds per key, counted separately. Requests to one do not use the other’s budget.
• The window is fixed. It starts with the key’s first counted request and ends 60 seconds later, not on the clock minute. Refused requests count but do not extend it, so waiting Retry-After seconds is always enough.
• A key has no rate-limit setting of its own, and the limit does not vary by plan. If Horizon cannot count a request, it serves it without the rate-limit headers.

Permission map

The Module permissions you set on a key are stored as a map of "<module>.<feature>": "<actions>", where actions are any of R (Read), W (Write), D (Delete) and X (Execute). Execute applies to workflow actions on /api/v2/forms/*, and no route on this page asks for it. Each group of agent routes requires one entry, and the HTTP method picks the action: GET needs R; POST, PUT and PATCH need W; DELETE needs D.

A missing action returns 403 PERMISSION_DENIED with the message API key lacks <action> permission for <module>.<feature> and details of { module, feature, action }.

A key with Full access (includes future features) stores the map {"*": "RWDX"} and no other entry. The * entry is used only when no entry names the feature, so it covers every feature, including features added after the key was created, and it holds every permission in the table above. It never grants an action a feature does not offer to keys, and it does not open the paths closed to keys.

On the module routes and /api/v2/forms/*, some features cap the actions any key can hold, whatever the map says. See Actions no key can hold. A request for a capped action gets the same 403, but the message goes on to say No API key can be granted <action> here: <reason>., and details adds capped: true, offered, the actions keys can hold there, and hint, which names what to use instead where there is something. None of the permissions in the table above is capped.

Board scope

A key’s Board access sets which boards it reaches:

A board or task outside the key’s scope returns 404 NOT_FOUND (Board not found or Task not found), never 403. An out-of-scope board cannot be told apart from one that does not exist. GET /boards lists only boards in scope. Labels and /users are organization-wide under every mode.

There is no board-role check on this surface. A key with company.boards D can delete any board in its scope.

Unscoped callers only

Seventeen routes, marked “unscoped only” in the endpoint table, refuse a key whose creator has a dimension grant that limits them to specific dimension values.

The refusal is a 403 in RFC 7807 form, not the usual error envelope:

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Your access is limited to specific dimension values. Sales covers all values and cannot be filtered."
}

Legal-entity separation

Each agent route resolves the active legal entity from the key creator’s membership. Whether a caller can observe any of it depends on the organization’s Multi-entity separation setting: Off, Standard or Strict, or Inherit, which follows Horizon’s platform default.

• Off: nothing narrows, X-Active-Legal-Entity has no effect, and no 403 comes from this step. The creator checks under Key checks still apply.
• Standard or Strict: list and read routes for boards, tasks, contacts, companies, deals and quotes return only records visible under the active entity, except that boards the key’s creator is a member of stay visible. A record outside it returns 404.
• X-Active-Legal-Entity naming an entity the creator cannot access returns 403 ENTITY_ACCESS_DENIED, as does * under Strict unless the creator has all-entities access or is an owner or admin.
• PUT and DELETE on a company the active entity does not own return 403 ENTITY_EDIT_DENIED. New boards and companies are stamped with the active entity.

Actor and write attribution

Who a request acts as:

• No X-Horizon-Agent-Deployment-Id: the actor is the key’s creator.
• With the header: the actor is that agent deployment, but only if an active skill on the deployment holds a horizon-api connection whose stored key is this key. Otherwise 403 AGENT_DEPLOYMENT_NOT_VERIFIED. The deployment must also be active: one that is paused, configuring, error or removed gets 403 AGENT_DEPLOYMENT_NOT_ACTIVE. The request is never downgraded to the creator.

Writes are attributed as follows:

• createdBy, updatedBy, completedBy and stage-history changedBy are the key creator’s Clerk user id, whichever actor applies.
• A comment’s author is the creator, or the agent deployment when the actor is an agent.
• When the actor is an agent, reading or updating a board, adding a column or section, creating or updating a task or subtask, and commenting add that deployment to the board as an editor member, for attribution.
• Deleting a contact, company, deal or quote records an audit entry in the same transaction: source AGENT, the key’s creator, the deployment when the actor is an agent, the request id, and a snapshot of the deleted record.

Endpoints

All paths are relative to https://api.horizonplatform.ai/api/v2/agent.

Responses

Every success wraps its payload as { "data": ... }. Deletes return 200 with a body, never 204. Identifiers are UUIDs, except user identifiers, which are Clerk user ids (user_...).

Errors use this envelope, where details appears only on some errors:

{
  "error": {
    "code": "MISSING_FIELDS",
    "message": "firstName and lastName are required"
  }
}

Two refusals use an RFC 7807 body instead: unscoped-only routes and the role check on POST /crm/quotes/:id/orders. Codes this surface raises beyond the ones above:

Pagination

Two styles, both newest first (createdAt descending):

GET /users returns at most 200 members, with no cursor. The other list routes are unpaginated.

Tasks

Task routes return the task row with no relations.

Create a task

POST /boards/:boardId/tasks returns 201 with the task. It reads only these fields from the body:

Two kinds of field are refused rather than ignored, anywhere in a task body:

• agentQueueStatus, agentQueueOrder, agentConversationId and skipQueueReconciliation return 400 DISPATCH_OWNED_FIELD, even when the value is null. The agent queue owns them.
• include returns 400 UNSUPPORTED_FIELD. The server chooses the returned shape.

Other unknown fields are dropped. labelIds is dropped on create; set labels with an update.

Update, move and delete

PUT /tasks/:taskId is a partial update. It accepts the create fields except that columnId is optional, plus:

Completing a task assigned to an agent, or changing its agent assignee, also sets that agent’s other working tasks in the organization to done.

PUT /tasks/:taskId/move takes columnId, position and targetBoardId, and nothing else:

• position is clamped to the destination column’s range; omit it to append.
• With targetBoardId, the destination must be in the key’s scope and the organization (404 Board not found otherwise), and columnId must name one of its columns (400 INVALID_COLUMN). A cross-board move without columnId fails the same way. The task’s section is cleared and its subtasks move with it.

DELETE /tasks/:taskId returns { "data": { "id": "..." } }.

Subtasks

POST /tasks/:taskId/subtasks takes title (required, 400 MISSING_FIELDS), description, assigneeType, assigneeUserId, assigneeAgentDeploymentId and dueDate, and returns 201. The subtask takes its parent’s column. A subtask cannot have subtasks: 400 INVALID_NESTING.

List and search

GET /boards/:boardId/tasks accepts limit, cursor and tabId. tabId applies a saved view’s filters; an unknown tabId returns the unfiltered list.

GET /tasks searches task titles, case-insensitively, across the boards the key can reach:

Comments

POST /tasks/:taskId/comments takes { "body": "..." }, which must be non-empty, and returns 201 with the comment. It needs two permissions, see Permission map.

Mentions are written inline as @[Display Name](user:<clerkUserId>) or @[Display Name](agent:<agentDeploymentId>). For each mention of a user or agent deployment in the organization, Horizon:

• adds them to the task’s board as an editor if they are not already a member
• starts a run of a mentioned agent on the task

Mentions of ids outside the organization stay in the text and have no effect.

Boards

Boards

GET /boards shows the creator’s view: an all-mode key does not list private boards its creator has not joined, but it can still fetch and change them by id.

The board body is not schema-validated on this surface. Unknown fields are ignored.

Columns, sections and members

Deletes return { data: { id } }.

Saved views (tabs)

Labels

Labels belong to the organization, not to a board, so board scope does not apply. POST /labels takes name (required) and color (default ""); PUT /labels/:labelId takes either. A label outside the organization returns 404 Label not found. GET /labels is sorted by name.

Sales

Create and update bodies are validated by the same schemas as the Sales module’s own /api/v2/erp/crm/* routes, which strip unknown fields. Each route then writes only the fields listed below. Other schema fields, such as a contact’s department or a company’s website, pass validation and are not stored by these routes.

ownerId is a Clerk user id and is not checked against the organization’s members.

customFields behaves differently by route. On PUT for contacts and companies it merges into the stored object: absent leaves it alone, null clears it, an object replaces the keys it names and deletes keys set to null, and anything else returns 400 INVALID_CUSTOM_FIELDS. On deal PUT, and on every create, the value sent replaces what is stored.

Contacts

lifecycleStage is one of lead, contact, customer, evangelist, opportunity, other (400 INVALID_STAGE).

Companies

All five company routes are unscoped only.

type is one of customer, vendor, prospect, partner. annualRevenue is a number or a decimal string. currencyCode is the company’s account currency, a three-letter ISO 4217 code such as EUR, stored upper-case. A non-blank value that is not three letters is 400 VALIDATION_ERROR; a three-letter code Horizon does not know is 400 INVALID_CURRENCY. On PUT, null or an empty string clears it. A new deal for the company starts in this currency when the request names none. Company responses include currencyCode.

address is a JSON object. Horizon reads the street (street, then line2), city, state, postalCode and country from it and sets the company’s street, city, state, postalCode and country fields to match; street holds both lines, separated by a line break. On PUT, only the parts whose value differs from the object already stored change those fields; null, {} or an object with no changed part leaves them as they are. Company responses include all five fields.

Deals

A deal line item is { productId, description, quantity, unitPrice, discountPercent, taxRate, sortOrder }. Only unitPrice is required, and quantity defaults to 1. A deal contact is { contactId, role }. POST takes at most 200 lineItems and 100 contacts (400 VALIDATION_ERROR). referralCompanyId names the company that referred the deal. Send a UUID or null; an empty string is 400 VALIDATION_ERROR. POST, GET /crm/deals and GET /crm/deals/:id return that company as referralCompany (id, name), null when the deal has none. companyId, contactId, referralCompanyId and pipelineId, and on create each line’s productId and each contact’s contactId, must belong to your organization (400 INVALID_COMPANY, INVALID_CONTACT, INVALID_REFERRAL_COMPANY, INVALID_PIPELINE or INVALID_PRODUCT), and nothing is written otherwise.

How taxRate is applied depends on whether the crm-pricing-canonical feature is on for your organization: on, it is a fraction (0.0825 is 8.25%); off, the stored line total treats it as a percent. The schema caps it at 9.9999 either way. Before a line’s total is worked out, quantity and unitPrice are rounded half up to four decimals, discountPercent to two and taxRate to four, and the line stores the rounded values.

Status follows the stage. A deal on a stage marked as won is won, on a stage marked as lost is lost, and on any other stage open. A deal that is won or lost has an actualCloseDate: the date you send, or otherwise the moment it closed. A deal moved from one won stage to another, or from one lost stage to another, keeps the close date it has unless you send a new one. Moving a won or lost deal to an open stage reopens it and clears the close date. Every stage change on PUT and change-stage records a stage-history row.

A status you send must agree with the stage the deal ends up on. won or lost is accepted for a deal on an open stage when its pipeline has no stage for that status, and for a deal whose stage is not in a pipeline. open is accepted on a won or lost stage when the pipeline has no open stage. Sending the status a deal already has changes nothing. actualCloseDate cannot be in the future: the latest date accepted is today in UTC+14 (400 VALIDATION_ERROR).

Winning a deal. When a PUT that changes stage, or a change-stage, moves a deal onto a stage of its pipeline marked as won, Horizon sets the deal’s company’s type to customer, and its payment terms to net 30 if it has none. Then, if your organization has Finance and the order-entry-quote-picker feature is off, it creates a Finance customer and a draft sales order, from the deal’s accepted quote, or from its line items when it has no accepted quote. Winning the same deal again does not make a second order. Creating a deal on a won stage does none of this.

The deal is saved before Finance runs, so the win stands whatever Finance does. When Finance cannot make the order for one of the reasons below, the call still answers 200, no Finance customer or sales order is created, a row on the deal’s History in Horizon says why, and data carries financeHandoff beside the deal’s fields:

{
  "data": {
    "id": "…",
    "stage": "Closed Won",
    "status": "won",
    "financeHandoff": {
      "setting": "sales_order",
      "outcome": "needs_legal_entity",
      "error": {
        "code": "AMBIGUOUS_LEGAL_ENTITY",
        "message": "This organization has more than one legal entity and none is set as primary, so Finance cannot tell which one the sales order belongs to. Set a primary legal entity in Settings > Entities."
      }
    }
  }
}

setting is always sales_order. Otherwise financeHandoff is absent: the sales order was made or already existed, the deal has no company to make one for, your organization does not have Finance, or the order-entry-quote-picker feature is on. Any other failure in the Finance step is answered as an error, with the deal already saved.

Quotes

All eight quote routes are unscoped only. A quote moves through these statuses:

A quote line item is { description, quantity, unitPrice, productId, discountPercent, taxRate, sortOrder }; description, quantity and unitPrice are required. The schema also accepts legalEntityId on create and dealId, companyId, contactId on update; these routes do not store them.

POST /crm/quotes/:id/orders turns an accepted quote into a sales order. Body { "definitionKey": "sales_order" }; it returns 201 { data: { id, orderNumber } }. Calling it again for the same quote returns the existing order with 201, but two concurrent calls can both create one. Refusals, in the order they are checked:

Organization members

Every route needs system.users. Members are returned as { id, clerkUserId, email, name, role, deactivatedAt, createdAt }.

role is one of owner, admin, department_lead, member, billing_admin, controller, accountant (400 VALIDATION otherwise). The key’s creator is the actor for every check: