Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shodai.network/llms.txt

Use this file to discover all available pages before exploring further.

API requests use the X-API-Key header. The TypeScript client sends that header when you pass apiKey to ApiClient; raw HTTP integrations must set the header directly. For testnet access, you can self-onboard at developers.shodai.network/portal and create an API key. You can use that key in your own integration or try it immediately in the Agreements API Playground. Production API keys are provisioned by your API operator, who hands the plaintext key to the recipient once.
Store the plaintext key when it is issued. The API stores only the hashed key afterward.

​
Send the API key

For SDK integrations, pass the key when constructing the client: 
import { ApiClient } from '@cns-labs/agreements-api-client';

const client = new ApiClient({
  baseUrl: process.env.BASE_URL!,
  apiKey: process.env.API_KEY,
});
For raw HTTP calls, send the same value as X-API-Key: 
curl -sS "$BASE_URL/v0/agreements" \
  -H "X-API-Key: $API_KEY"

​
Scopes and entitlements

API access is controlled by entitlements on the API principal. Testnet keys created through the Developer Portal are intended to include the default agreement read and write scopes. Manually provisioned principals should be checked for the scopes your integration needs.
ScopeUse
agreements.readRead agreement records, state, and input history.
agreements.writeValidate, deploy, and submit agreement inputs.
agreements.*Wildcard access for agreement scopes.
*Broad wildcard access. Use only for internal testing.
Entitlement modes are:
ModeResult
free_allowlistAllows the scoped operation.
blockedReturns 403 Forbidden for the scoped operation.
paid_requiredReturns 402 Payment Required for future x402-style enforcement.
If the principal has no active entitlement for the requested scope, the API returns 403 Forbidden.

​
Common authentication failures

StatusMeaningWhat to check
401Missing, invalid, revoked, or disabled API key.Confirm the X-API-Key header is present and uses the current plaintext key.
402The key is authenticated but the entitlement mode is paid_required.Ask your API operator to review the entitlement mode for the requested scope.
403The key is authenticated but not allowed for this scope or resource.Confirm the principal has agreements.read, agreements.write, agreements.*, or * as appropriate, and that no blocked entitlement applies.

​
Header casing

API auth is case-insensitive at the HTTP layer, but examples use X-API-Key consistently.