Skip to content
deedglassdocs

REST API overview

The API is JSON over HTTPS under /v1. Every endpoint is in the endpoint reference, generated from api/openapi.yaml, the same file a test keeps equal to the server’s routes.

Conventions

Section titled “Conventions”
  • Objects carry "object": "<type>" and an "id" with a prefix: act_, deed_, agt_, pol_, … (Ids). Ids are lowercase.
  • Timestamps are RFC 3339 in UTC.
  • Money is amount in minor units (an integer) plus currency (ISO 4217, lowercase): {"amount": 12000, "currency": "usd"} is $120.00.
  • Every response carries Deedglass-Request-Id and the Deedglass-Version it was answered with.
  • CORS is closed, except for the public key set and the MCP protected-resource metadata.

Errors

Section titled “Errors”

Every error has the same envelope and a page of its own:

HTTP 400 · invalid_request_error
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "`limit` must be between 1 and 100.",
    "param": "limit",
    "request_id": "req_01j9zr3m5k8q2w7x4t6v0b1c9d",
    "doc_url": "https://docs.deedglass.com/errors/validation_failed"
  }
}

Branch on type and code, never on the message. See every error code.

The pages in this section

Section titled “The pages in this section”