Surfaces: REST API

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

Declaring 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"

This machine is now reachable at POST /api/tickets/classify with bearer token authentication.

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"

Calling the API

Local cell

When running locally, the API is available on your cell’s port (default 9000):

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
}

Cloud cell (mashin.live)

After deploying to mashin.live, the API is available on your organization’s subdomain:

curl -X POST https://myorg.mashin.live/api/tickets/classify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"message": "My deploy is failing with exit code 137"}'

Via tunnel

If you are running locally but need a public URL (for testing, demos, or external integrations), the tunnel exposes your API through mashin.live:

mashin tunnel ticket_classifier.mashin
# Shows: https://mashin.live/tunnel/ticket_classifier/api/tickets/classify

Authentication

Bearer token

expresses
  api
    path: "/api/classify"
    authentication: "bearer_token"

Clients send an Authorization: Bearer <token> header. The token is verified against the cell’s credentials.

API key

expresses
  api
    path: "/api/classify"
    authentication: "api_key"

Clients send the key as an X-Api-Key header or ?api_key= query parameter.

No authentication

expresses
  api
    path: "/api/classify"
    authentication: "none"

Or simply omit the authentication field. The endpoint is open. Governance still applies: the machine’s ensures section is enforced regardless of authentication.

Multiple endpoints

A machine can expose multiple API endpoints:

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

Request and response format

Request

The request body maps to the machine’s accepts section. For POST/PUT requests, send JSON:

{
  "message": "My deploy is failing"
}

For GET requests, inputs map to query parameters:

/api/tickets/classify?message=My+deploy+is+failing

Response

The response body matches the machine’s responds with section:

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

Errors return structured error responses:

{
  "error": "governance_denied",
  "message": "Machine does not have permission: reason",
  "code": 403
}

Governance

Every API request goes through the full governance pipeline:

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

A denied request returns HTTP 403 with the governance reason.

CORS

For browser-based clients, the API automatically handles CORS preflight requests. The default policy allows all origins. To restrict origins, configure CORS at the cell level.

Next steps

• Webhooks - Receive events from external services
• WebSocket - Real-time connections
• Surfaces overview - All surface types