REST API Reference

This page is the narrative companion to the live, generated REST API reference.

• Interactive reference: browse every endpoint, view request/response schemas, and try requests against your own organisation.
• OpenAPI specification
• Go SDK: prefer the Go SDK reference for production code; the SDK wraps every endpoint described here.

Base URL

CRE Connect is offered as a managed service. Use the base URL provided to your organisation when you onboarded:

https://cre-connect.api.chain.link/v1

Reach out to the Chainlink team if you don't yet have an environment URL or need a separate sandbox.

Authentication

Every request requires an organisation API key, sent in the Authorization header with the Apikey scheme:

curl https://cre-connect.api.chain.link/v1/networks \
  -H "Authorization: Apikey $CREC_API_KEY"

The OpenAPI specification declares this scheme as ApiKeyAuth:

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: Authorization
    description: |
      Organisation API key. Send as `Authorization: Apikey <key>`.
security:
  - ApiKeyAuth: []

Treat API keys as secrets: they grant full access to your organisation's channels, watchers, wallets, and operations. Rotate any key that may have been exposed.

Endpoint groups

Full request/response schemas live in the interactive reference.

Async semantics

A small number of endpoints are asynchronous and return 202 Accepted rather than the final state:

• PATCH /channels/{channel_id}/watchers/{watcher_id} with a status transition to archived returns 202 and a watcher in the archiving state. The watcher transitions to archived (or archive_failed) once CRE Connect deprovisions it. Poll the watcher resource, or subscribe to watcher.status events, to observe the terminal state.
• POST /channels/{channel_id}/operations returns the operation in either the accepted state (when a signature is provided) or the pending_signature state (when the signature is omitted, creating a draft). Confirmation or failure is reported via operation.status events or follow-up GETs. On networks with multiple active finality stages, the same operation can emit confirmed_latest, confirmed_safe, and confirmed as the block matures. See Submit and Track Operations and Multi-Event Finality.
• PATCH /channels/{channel_id}/operations/{operation_id} with {status: "accepted", signature, digest} finalizes a draft operation from pending_signature to accepted. With {status: "cancelled"}, it cancels a draft. See Draft Operations.
• POST /channels/{channel_id}/queries returns 202 Accepted with the query in the accepted state. The DON executes the query asynchronously; terminal state (completed / failed) is reported via query.status events or follow-up GETs. Queries expire after a TTL if no terminal callback arrives. See Chain Queries.

For a complete state-machine reference for every async resource, see Lifecycles.

Error responses

All non-2xx responses use a uniform ApplicationError shape:

{
  "type": "NOT_FOUND",
  "code": "WALLET_NOT_FOUND",
  "message": "The requested resource was not found."
}

type is one of:

The code field provides a machine-readable error code. For NOT_FOUND responses, the code identifies which resource was not found:

For CONFLICT responses, the code identifies the specific conflict:

The Go SDK maps these codes to sentinel errors (apierror.ErrChannelAlreadyExists, etc.) so errors.Is works across packages; see Error Handling.

message is a human-readable explanation that may change between releases: never key business logic on its exact text.

Authentication errors

Calls without a valid Authorization: Apikey <key> header return 401 Unauthorized. The body uses the same ApplicationError shape.

Rate limiting

When rate limits apply, the API returns 429 Too Many Requests. The Go SDK's polling helpers (watchers.WaitForActive / WaitForArchived) classify 429 and 5xx as transient and continue to the next poll tick rather than aborting; for every other endpoint the SDK does not retry: implement your own retry logic in your application code. See Error Handling for the full classification.

Pagination

Listing endpoints (/wallets, /channels, /channels/{id}/watchers, /channels/{id}/operations, /channels/{id}/queries, /channels/{id}/events) return:

{
  "data": [...],
  "has_more": true
}

When has_more: true, paginate using the endpoint-specific cursor parameters (limit, offset, or a time-based cursor; see the interactive reference for each endpoint's exact contract).

Versioning

The OpenAPI document declares info.version. The current spec is 0.8.0. Backwards-incompatible changes are limited to major-version bumps; minor bumps may add new optional fields and endpoints. Pin your dependencies (Go SDK, generated clients) to a known minor.

Try it

The fastest way to validate authentication is to call ListNetworks:

curl https://cre-connect.api.chain.link/v1/networks \
  -H "Authorization: Apikey $CREC_API_KEY" \
  | jq

A successful response returns { "data": [...], "has_more": false }. See Authentication for an end-to-end smoke test using the Go SDK.

See also

• Interactive REST reference
• Go SDK reference
• Error handling
• Lifecycles