API, SDK, CLI, and Webhook Contracts

Draft 0.1 — 2 August 2026
This document defines interface expectations. Endpoint names and provider choices remain implementation decisions until released in a versioned API specification.

Objective

ANUKA must be equally usable by:

first-party web applications;
resident products;
browser extensions;
integration partners;
automation scripts;
command-line users;
AI agents;
independent protocol implementations.

The rule is:

Every important capability must have a stable machine interface before it becomes trapped inside one user interface.

Interface surfaces

Public API

Used by approved external applications and resident products.

It exposes stable, documented capabilities with explicit authentication, authorization, quotas, compatibility, and support policies.

Product API

A resident product may expose its own endpoints while reusing ANUKA identities, events, and schemas.

Product APIs must not imply Foundation operation or support unless explicitly stated.

Internal service API

Used between trusted ANUKA-operated components.

Internal does not mean undocumented. Internal interfaces still require schemas, owners, authentication, and compatibility policy.

Webhook API

Delivers events to subscriber-controlled endpoints.

Webhooks are asynchronous notifications, not an authoritative query interface.

SDKs

Language-native wrappers that make the APIs easier to use without inventing different semantics.

CLI

A scriptable command-line interface for humans, CI, operators, and agents.

Agent tools

Purpose-specific tool contracts exposed through MCP or another approved agent protocol.

Agent tools should call the same core application capabilities rather than bypassing them.

OpenAPI baseline

HTTP APIs are described using OpenAPI.

For the first implementation, ANUKA may choose either:

OpenAPI 3.1.2 for broad tooling compatibility and alignment with JSON Schema 2020-12; or
OpenAPI 3.2.0 after confirming required generators, validators, gateways, and documentation tools support it reliably.

The selected version must be recorded in an ADR and pinned per API release.

The specification text is authoritative over generated schema artifacts when they conflict.

API design principles

resource-oriented where it improves clarity;
capability-oriented for actions that do not map cleanly to CRUD;
stable identifiers;
explicit state transitions;
idempotent retries;
narrow authorization;
predictable pagination;
structured errors;
traceable operations;
no hidden side effects;
safe defaults;
documented consistency.

Base URL and versions

Recommended pattern:

https://api.anuka.network/v1/

Major compatibility version appears in the URL or negotiated media type.

Minor compatible improvements do not require a new base path.

The API version is separate from:

schema version;
SDK version;
resident-product version;
event major version;
MCP protocol version.

Resource paths

Prefer plural nouns and stable nesting.

Examples:

GET  /v1/products/{product_id}
GET  /v1/products/{product_id}/opportunities
POST /v1/opportunities/{opportunity_id}/applications
POST /v1/contributions/{contribution_id}:submit
POST /v1/consent-requests/{request_id}:approve
POST /v1/agent-tasks/{task_id}:cancel

Action suffixes are appropriate when the operation has meaningful domain semantics and is not a simple field update.

HTTP methods

GET reads without changing business state;
POST creates resources or invokes non-idempotent domain actions with an idempotency key;
PUT fully replaces a resource when the contract supports replacement;
PATCH performs a defined partial update;
DELETE requests deletion or deactivation according to resource semantics.

A GET endpoint must not trigger payments, approvals, tool execution, or other material mutations.

Authentication

Supported client types may include:

user-interactive OAuth clients;
confidential server clients;
service workloads;
browser extension clients;
CLI device or browser authorization flows;
approved AI-agent hosts.

Long-lived static API keys should be limited to narrow use cases and replaced with scoped, rotatable credentials where possible.

Authorization

Every operation documents:

required capability;
permitted principal types;
resource scope;
relevant organization or product boundary;
required consent or delegation;
minimum assurance where applicable;
high-risk approval requirements.

A successful authentication does not grant access to all API resources.

OAuth scopes and authorization details

Simple scopes describe coarse API areas.

Rich Authorization Requests or equivalent typed grants describe detailed actions and resources.

Example scope:

contributions.read

Example detailed authorization:

{
  "type": "anuka_contribution_access",
  "actions": ["read_evidence"],
  "contribution_ids": ["ctr_123"],
  "purpose": "release_review",
  "expires_at": "2026-08-03T12:00:00Z"
}

A broad scope must not override a narrower resource or consent restriction.

Idempotency

Mutating endpoints that may be retried accept:

Idempotency-Key: <client-generated-value>

The server binds the key to:

principal;
endpoint and action;
resource scope;
normalized request hash;
original response;
retention period.

Reusing a key with different input returns a conflict error.

Concurrency control

Resources with conflicting updates should support optimistic concurrency.

Options include:

ETag and If-Match;
explicit revision number;
state transition preconditions.

Example:

If-Match: "revision-7"

A stale mutation fails instead of silently overwriting a newer decision.

Pagination

Cursor pagination is preferred for changing collections.

Example response:

{
  "data": [],
  "page": {
    "next_cursor": "opaque-value",
    "has_more": true
  }
}

Cursors are opaque and must not be parsed by clients.

Endpoints document:

default and maximum page size;
stable ordering;
cursor lifetime;
behavior when records change;
filtering and sorting capabilities.

Offset pagination may be used for stable, small administrative lists.

Filtering

Filtering uses documented fields and operators.

Avoid executing arbitrary user-provided query languages against production data unless isolation, authorization, complexity limits, and privacy behavior are explicit.

Unknown filters should fail rather than be silently ignored.

Field selection and expansions

Clients may request optional expansions or field groups when this reduces round trips.

Example:

GET /v1/contributions/ctr_123?expand=review_summary,evidence_status

Expansions never bypass authorization. Restricted subresources are omitted or rejected according to the endpoint contract.

Errors

Errors are structured and stable.

Example:

{
  "error": {
    "code": "consent_required",
    "message": "The requested evidence requires holder approval.",
    "request_id": "req_123",
    "details": {
      "consent_request_id": "cnr_456"
    }
  }
}

Error fields:

machine-readable code;
safe human-readable message;
request or correlation ID;
structured details;
documentation link where appropriate;
retry guidance where safe.

Error messages must not leak secrets, private existence, authorization policy, or internal stack traces.

Error categories

At minimum:

authentication required;
authorization denied;
consent required;
validation failed;
conflict or stale revision;
rate limited;
dependency unavailable;
temporarily restricted by incident policy;
resource not found;
unsupported version;
internal error.

A client must not infer that a resource exists when it is unauthorized to know that fact.

Rate limits and quotas

Rate limits may be applied by:

principal;
organization;
product;
IP or network risk signal;
endpoint;
cost class;
tool or model budget.

Responses should include standard or documented rate-limit metadata.

Expensive endpoints require cost controls and bounded input sizes.

Request limits

Each endpoint declares:

maximum payload size;
attachment limits;
maximum array lengths;
schema depth;
timeout behavior;
synchronous versus asynchronous processing threshold.

Large evidence packages should use direct object-storage upload flows rather than pass through application servers unnecessarily.

Asynchronous operations

Long-running work returns an operation or task resource.

{
  "task_id": "tsk_123",
  "status": "queued",
  "status_url": "/v1/agent-tasks/tsk_123"
}

Tasks support:

status;
progress where safe;
result reference;
error state;
cancellation request;
expiry;
audit trail.

A request timeout does not necessarily mean the underlying operation failed. Idempotency and task status prevent duplicate execution.

Webhook subscriptions

A subscription declares:

endpoint URL;
event types;
product and organization scope;
schema versions;
secret or key material;
status;
retry policy;
data classification ceiling;
expiry or review date.

Subscribers receive only events they are authorized to receive.

Webhook signing

Webhook deliveries must be authenticated.

A signature scheme should include:

timestamp;
event or delivery ID;
raw request body;
key identifier;
algorithm identifier.

Receivers must:

verify signature before parsing trusted content;
enforce timestamp tolerance;
protect against replay;
rotate secrets or keys;
preserve raw body bytes for verification;
return success only after durable acceptance.

Webhook retries

Deliveries use bounded exponential backoff with jitter.

Retry policy documents:

retryable status codes;
maximum delivery period;
attempt metadata;
disablement conditions;
dead-letter or recovery behavior;
manual redelivery capability.

Webhooks are at-least-once. Receivers deduplicate using stable event or delivery IDs.

Webhook privacy

A webhook payload must not include full private records by convenience.

Prefer event references and minimal summaries. The receiver can retrieve authorized details through the API.

Example:

{
  "type": "network.anuka.contribution.accepted.v1",
  "subject": "ctr_123",
  "data": {
    "product_id": "prd_456",
    "status": "accepted"
  }
}

SDK strategy

Official SDKs should be generated from the canonical OpenAPI contract where practical, then wrapped with carefully reviewed ergonomic helpers.

Initial priorities may include:

TypeScript;
Python;
Go.

Each SDK must preserve API semantics rather than rename concepts inconsistently.

SDK guarantees

An SDK documents:

supported API versions;
runtime versions;
authentication helpers;
retry defaults;
timeout defaults;
pagination iterators;
error types;
idempotency behavior;
telemetry hooks;
release and deprecation policy.

Automatic retries must not retry unsafe operations without idempotency protection.

SDK extensibility

SDKs should allow:

custom HTTP transport;
proxy configuration;
timeout configuration;
telemetry injection;
test doubles;
endpoint override for staging or self-hosted implementations;
additional headers within an approved namespace.

They must not allow callers to bypass TLS or signature verification through an innocent-looking default.

CLI objectives

The ANUKA CLI should be useful for:

authentication;
inspecting current principal and grants;
managing products and environments;
validating schemas;
publishing test events;
managing opportunities and contributions;
reviewing consent requests;
invoking approved agent tools;
exporting records;
checking conformance;
operational diagnostics.

CLI output modes

Human-readable output is the default for terminals.

Machine-readable modes include:

--output json
--output jsonl
--output yaml

Machine output must remain stable within a major CLI version and must not mix progress text into stdout.

Diagnostics and progress go to stderr.

CLI safety

Destructive or high-impact commands should support:

explicit resource display;
dry run;
confirmation prompt for interactive use;
--yes only with explicit parameters;
idempotency keys;
audit reason;
environment highlighting;
denial of ambiguous production targets.

An AI agent must not be able to bypass a required approval by passing --yes.

CLI authentication

The CLI should use a browser or device authorization flow and secure local credential storage.

Tokens should be:

scoped;
short-lived where practical;
refreshable under policy;
revocable;
separated by environment and profile.

Plaintext credentials in shell history or project files are prohibited.

Contract generation

The repository should generate:

rendered API reference;
typed SDK models;
validation schemas;
mock server fixtures;
example requests;
CLI completion data;
changelog entries;
conformance tests.

Generated artifacts are reproducible and tied to a source commit and digest.

API changelog

Every release records:

added endpoints and fields;
behavior changes;
deprecated features;
security changes;
known incompatibilities;
migration instructions;
removal dates.

A field marked deprecated remains functional through the declared support window unless an emergency security decision requires earlier action.

Compatibility testing

CI should test:

OpenAPI validation;
breaking-change detection;
examples against schemas;
SDK compilation;
generated client smoke tests;
webhook signature fixtures;
idempotency behavior;
pagination behavior;
CLI machine-output snapshots;
authorization denial cases;
privacy filtering.

Sandbox

ANUKA should offer a sandbox or test environment with:

non-production data;
test identities and products;
payment-provider test mode;
webhook inspection;
deterministic test scenarios;
lower risk limits;
reset capability.

Sandbox behavior must not create false assumptions about production compliance, scale, or payment timing.

Documentation requirements

Every endpoint and tool documents:

purpose;
required capability;
data classification;
request and response schema;
side effects;
idempotency;
consistency;
error behavior;
limits;
example;
version status;
relevant legal or policy boundary.

MVP contract set

The first public interface should prioritize:

current principal and organization context;
product registry and presence manifest;
opportunities and applications;
contributions and reviews;
evidence presentation requests and consent;
stewardship grants;
agent task submission and approval;
webhook subscriptions;
export and conformance validation.

Financial mutation endpoints should remain narrow and provider-backed until dedicated operational controls are complete.

Acceptance criteria

OpenAPI is the source of truth for HTTP shape;
JSON Schema validates shared payloads;
every mutation supports safe retry behavior;
authorization requirements are machine-readable;
errors are stable and privacy-safe;
pagination is predictable;
webhooks are signed, replay-resistant, and minimal;
SDKs do not invent different business semantics;
CLI machine output is stable;
destructive actions cannot bypass required approvals;
breaking changes are automatically detected;
generated artifacts are reproducible.

Sources

Verification record

Sources opened and checked: 2 August 2026
OpenAPI release observed: 3.2.0 and 3.1.2 published 19 September 2025
Initial OpenAPI implementation version: ADR required
SDK languages: Draft priority only