api

Esta página aún no está disponible en tu idioma.

The api surface exposes a machine as a REST endpoint. Any HTTP client, whether a browser, mobile app, cURL command, or external service, can invoke the machine by making an HTTP request to the configured path.

Overview

Declaring an api surface gives a machine a URL. Requests to that URL are validated against the machine’s accepts contract, run through governance, executed, and returned as JSON. Authentication is configurable per endpoint. Multiple API surfaces can be declared on a single machine (for example, GET and POST on the same path).

Syntax

expresses
  api
    path: "/api/tickets/classify"
    method: "POST"
    authentication: "bearer_token"

A complete machine with an API surface:

machine ticket_classifier

  accepts
    message as text, is required

  responds with
    team as text
    confidence as decimal

  ensures
    permissions
      allowed to
        reason

  implements
    ask classify, using: "anthropic:claude-haiku-4-5"
      with task "Classify this support ticket: ${input.message}"
      returns
        team as text
        confidence as decimal
      assuming
        team: "engineering"
        confidence: 0.91

  expresses
    api
      path: "/api/tickets/classify"
      method: "POST"
      authentication: "bearer_token"

Configuration options

Config	Required	Default	Description
`path`	Yes	-	URL path for the endpoint
`method`	No	`"POST"`	HTTP method: `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`
`authentication`	No	`"none"`	Auth type: `"bearer_token"`, `"api_key"`, `"none"`

Authentication types

Auth	Header	Notes
`"bearer_token"`	`Authorization: Bearer <token>`	Token verified via cell credentials
`"api_key"`	`X-Api-Key: <key>` or `?api_key=<key>`	Key as header or query parameter
`"none"`	(no header)	Open endpoint; governance still applies

Request and response format

For POST/PUT, send JSON matching the accepts fields. For GET, inputs map to query parameters. The response body matches responds with as JSON. Errors return structured responses with error, message, and code fields.

Governance

Every API request goes through the full governance pipeline:

Authentication is verified (if configured)
Inputs are validated against the accepts contract
The governance interpreter checks permissions from ensures
The machine executes
A SurfaceAccess event is recorded with :api surface in the behavioral ledger
The result is returned as JSON

A denied request returns HTTP 403 with the governance reason. An invalid signature or missing token returns HTTP 401.

Example

Calling the API locally:

curl -X POST http://localhost:9000/api/tickets/classify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -d '{"message": "My deploy is failing with exit code 137"}'

Response:

{
  "team": "infrastructure",
  "confidence": 0.94
}

Multiple endpoints on one machine:

expresses
  api
    path: "/api/orders"
    method: "GET"
    authentication: "api_key"
  api
    path: "/api/orders"
    method: "POST"
    authentication: "bearer_token"

api