API pipeline: Give your oracle tools

Index: API pipelines — index

Goal: give your oracle tools: describe your own HTTP endpoints as cards and store the keys they need as secrets, then attach both to the oracle's agenda.

An API endpoint card is one HTTP call the oracle may make; its operation_id is the tool's name, its request_schema the tool's arguments. A secret holds a key; endpoints reference it by name and the value is filled in only when the call is made.

Steps

1. Store the key.

POST /v0/my/secrets
Idempotency-Key: sec-0a9d…
{"key_name": "secret_shop_api_token", "value": "sk-example-123", "host": "api.example.com",
 "title": "Shop API token", "workspaces": ["470000000000000400"]}
→ {"nonce": "470000000000000410", "key_name": "secret_shop_api_token", "host": "api.example.com",
   "title": "Shop API token", "created_at": "…", …}

• key_name: secret_ + [a-z0-9_], 8–64 characters; the convention is secret_<name>_<role>.
• value is write-only: no call ever returns it. To change it, delete the secret and create a new one.
• host: the value is only ever sent to this host. Always set it.
• workspaces (required, at least one of yours): where the secret is filed.

2. Describe the endpoint.

POST /v0/my/api_endpoints
Idempotency-Key: ep-77b3…
{"title": "Check order status", "content": "Returns the status of one order. Use when a customer asks where their order is.",
 "operation_id": "orders_status", "method": "GET",
 "path": "https://api.example.com/v1/orders/{id}",
 "request_schema": {"type": "object", "properties": {"id": {"type": "string"}}, "required": ["id"]}}
→ {"nonce": "470000000000000420", "card_type": "api_endpoint", …}

• Required: title, operation_id, method, path. method is upper-cased (GET, POST, PATCH, PUT, DELETE).
• path: a full URL, or a path starting with / plus domain (the host it goes to).
• Reference a secret where the service expects its key as {{secret_<key name>}}, or by role as {{secret_*_<role>}} (exactly one secret with that role must be attached). Secrets bound to different hosts cannot be mixed in one endpoint.
• content tells the oracle when to use it; response_schema is optional.

3. Attach to the agenda. PATCH /v0/my/agendas/{agenda} {"api_endpoints": ["470000000000000420"], "secrets": ["470000000000000410"]} — each list replaces the previous one. API pipeline: Write an agenda for your oracles

4. Manage.

• Endpoints: PATCH /v0/my/api_endpoints/{nonce} (any field above, handle, visibility), DELETE …, GET /v0/my/api_endpoints, public ones GET /v0/graph/api_endpoints (+ /{nonce}).
• Secrets: GET /v0/my/secrets (names and hosts, never values), PATCH /v0/my/secrets/{nonce} (title, content, host, visibility), DELETE /v0/my/secrets/{nonce}.

Behind

• The secret value is decrypted only when the oracle calls the endpoint, and goes only to the secret's host.
• Someone you gave write on an endpoint can edit its text but cannot change where it sends or add secret references; only the owner can change domain, host, visibility or rights.

Rules

• 400: title is required; operation_id, method and path are required; value is required; a secret must be placed into a workspace; key name: must start with secret_, length must be 8..=64, only [a-z0-9_] allowed.
• 403: only the card owner can change where the endpoint sends; only the card owner can add secret references: …; owner-only fields changed by a grantee.
• At call time a missing or ambiguous secret role, or secrets bound to different hosts, stop the call.

API surface