Business API contract draft v0.1
Define resources, identity, pagination, asynchronous work, idempotency and errors for review.
Scope and prerequisites
This draft proposes third-party business resources. Internal client routes are not declared stable public APIs. Before use, implement endpoint provisioning, credential issuance, tenancy, authorization, limits, records and a test environment. Paths, scopes and fields below are proposals.
Identity, organization and least privilege
Issue revocable, expiring service identities with company/project scopes such as projects:read and task-requests:create. Validate identity, resource ownership and operation grants on every request; never trust a supplied companyId alone. Keep secrets server-side, outside browser bundles and app manifests. Finalize OAuth or service-token issuance before release.
Proposed minimum resources
Start with reads and submission of requests for review. Submission is not execution and does not bypass approval. This draft excludes approval actions and consequential tool operations.
| Method and path | Meaning | Proposed scope |
|---|---|---|
| GET /v1/projects | List authorized projects with cursor pagination | projects:read |
| POST /v1/task-requests | Create a request; return 202 and an identifier | task-requests:create |
| GET /v1/task-requests/{id} | Read status, result reference and failure reason | task-requests:read |
Request and asynchronous response
Use UTF-8 JSON, ISO 8601 timestamps with timezone and opaque identifiers. Source references must resolve to authorized resources, not arbitrary internal URLs. This request describes work and acceptance criteria. HTTP 202 means accepted, not completed.
POST /v1/task-requests HTTP/1.1
Authorization: Bearer SCOPED_SERVICE_TOKEN
Content-Type: application/json
Idempotency-Key: req-20261116-report-001
{
"projectId": "prj_example",
"objective": "Prepare a read-only weekly report",
"sourceRefs": ["source_example"],
"acceptance": "Totals reconcile; cite source records"
}
HTTP/1.1 202 Accepted
Location: /v1/task-requests/tr_example
Content-Type: application/json
{"id":"tr_example","status":"accepted","requestId":"rq_example"}Pagination, rate limits and idempotency
List responses propose items and nextCursor, with default limit 50 and maximum 100, pending implementation. Deduplicate writes by service identity, company, route and Idempotency-Key; reject conflicting payloads. Publish the retention window before release. Use bounded backoff for 429 and retryable failures, honoring Retry-After. After timeouts, query status before resubmitting with a new key.
Errors, states and observability
Use RFC 9457 application/problem+json with stable code and requestId extensions, excluding secrets, internal paths and other tenants' resources. Distinguish input, authentication, authorization, visibility, conflict, rate-limit and service errors. Proposed work states are accepted, running, awaiting_review, succeeded, failed and cancelled; confirm terminal states from durable results.
{
"type": "about:blank",
"title": "Conflict",
"status": 409,
"detail": "The idempotency key was used with a different payload.",
"code": "IDEMPOTENCY_CONFLICT",
"requestId": "rq_example"
}Checks before a public release
Release requires a machine-readable definition, identity and tenancy tests, limits, idempotency windows, async timeout semantics, compatibility policy and operational ownership. Test cross-company denial, inaccessible resources, duplicates, status after disconnection and version compatibility. Until then, this page supports design review rather than claiming an available API.