REST API Reference

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

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.

Roles and API key permissions

Member roles and API key scopes serve different purposes. Role callouts identify the member role needed for a UI task or to grant the corresponding permissions to a key. API calls are authorized by the permissions selected for the key.

CRE Connect Viewer includes read permissions. Operator adds resource creation and updates, query creation, and operation submission, finalization, or cancellation. Admin also includes wallet, channel, and watcher archival. The organization Owner has every permission, but a key remains limited to its selected scopes. See RBAC and API Keys.

Signer authorization on a Smart Account and DTA contract roles are separate from Platform member roles. A chain query also needs crec:query:write to create the query resource even though the EVM call is read-only.

Endpoint groups

Path prefixResourceNotes
/health-checkService livenessAnonymous; no auth required.
/networksSupported networksList runtime-discovered networks.
/walletsSmart AccountsCreate, list, lookup, rename, archive.
/channelsChannelsCreate, list, lookup, rename, archive.
/channels/{id}/watchersWatchers within a channelCreate with service or ABI; archive (async).
/channels/{id}/operationsOperations within a channelCreate, execute, finalize, or cancel; track lifecycle.
/channels/{id}/queriesChain queries within a channelCreate (async 202), list, lookup.
/channels/{id}/eventsEvents on a channelReal-time poll.
/channels/{id}/events/searchHistorical event searchFilter by type, time, address, etc.
/channels/{id}/events/search/{event_id}Single event lookupFetch one event by ID.

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:

typeTypical HTTP statusMeaning
VALIDATION_ERROR400Invalid input: schema validation or parameter constraint failed.
NOT_FOUND404The referenced resource does not exist (or is not visible to your org).
CONFLICT409A unique constraint or state transition guard was violated.
INTERNAL_ERROR500Server-side error. Safe to retry.
ORGANIZATION_NOT_FOUND401The authenticated organization is not onboarded in CRE Connect.

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

codeMeaning
CHANNEL_NOT_FOUNDThe referenced channel does not exist.
WALLET_NOT_FOUNDThe referenced wallet does not exist.
OPERATION_NOT_FOUNDThe referenced operation does not exist.
WATCHER_NOT_FOUNDThe referenced watcher does not exist.
QUERY_NOT_FOUNDThe referenced query does not exist.

For CONFLICT responses, the code identifies the specific conflict:

codeMeaning
CHANNEL_ALREADY_EXISTSA channel with the same name already exists in the organization.
WALLET_ALREADY_EXISTSA wallet with the same name already exists in the organization.
WATCHER_ALREADY_EXISTSA watcher with the same name already exists in the channel.
IDEMPOTENCY_KEY_MISMATCHAn idempotency key was reused with a different request.
OPERATION_NOT_FINALIZABLEThe operation is not in a finalizable state.
OPERATION_NOT_CANCELLABLEThe operation is not in a cancellable state.
OPERATION_DEADLINE_ELAPSEDThe operation deadline has elapsed.
RESOURCE_VERSION_CONFLICTThe resource was modified concurrently by another request.
WALLET_ALREADY_ARCHIVEDThe wallet is archived and can no longer accept operations.
CHAIN_UNAVAILABLEThe chain is unavailable for wallet creation.

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

Required role:

CRE Connect Viewer

or higher

What each role can do

The GET /networks smoke test requires crec:network:read in your API key. A successful response confirms network read access; it does not prove that the key can create or archive resources.

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

Get the latest Chainlink content straight to your inbox.