DocsDeveloper integration

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.

Proposed endpoints, not a public service
Method and pathMeaningProposed scope
GET /v1/projectsList authorized projects with cursor paginationprojects:read
POST /v1/task-requestsCreate a request; return 202 and an identifiertask-requests:create
GET /v1/task-requests/{id}Read status, result reference and failure reasontask-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.

http
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.

json
{
  "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.

All documentationNext guide

Still have a question?

Explore expert support