REST API v400 quickstart

Use the public OpenAPI specification as the contract for paths, parameters, schemas, and authentication. The API Reference presents that contract interactively. Requests reach your selected project's real data; begin with reads.

Project, language, and authentication

The base URL is https://api.ordering.co/v400/<language>/<project>. Use your project's actual code and language, such as en; the example demo in the specification does not identify your project or provide a sandbox. A wrong project code cannot be corrected by changing credentials.

Create a REST API key in the Dashboard's API Keys settings. The public developer quickstart sign-in page can deliver a separate REST key when you select Also give my agent the REST API. Cloning the helper does not require GitHub membership; access to project data still requires your own Ordering account and consent.

Inspect each operation's security block:

Security scheme	Credential
apiKeyAuth	REST API key in X-Api-Key. Never put it in Authorization.
bearerAuth	Session JWT from POST /auth in Authorization: Bearer <session token>.
Empty operation security ([])	Public operation; no credential required.

An MCP key cannot authenticate REST requests. API keys have no MCP read/write scope and do not expire; they act with your permissions until revoked. Keep keys on the server in environment variables or a secret manager, outside browser/mobile bundles and version control. Do not log authorization headers or customer responses.

Get the latest five orders

GET /orders accepts API-key or session authentication. Without mode=dashboard, the operation scopes results to the caller's customer orders. Dashboard mode applies the operational user's role permissions; it does not bypass access checks. The quickstart's current example orders by descending ID:

# In an authorized quickstart checkout; the helper reads its local credentials.
./ordering api GET "/orders?orderBy=-id&page=1&page_size=5&mode=dashboard"

For a server integration, provide ORDERING_API_KEY, ORDERING_PROJECT, and ORDERING_LANGUAGE in its private environment. The following Node.js example makes one read without hardcoded credentials:

const { ORDERING_API_KEY, ORDERING_PROJECT, ORDERING_LANGUAGE } = process.env;
if (!ORDERING_API_KEY || !ORDERING_PROJECT || !ORDERING_LANGUAGE) {
  throw new Error('Set API key, project code, and language in the server environment');
}
const base = `https://api.ordering.co/v400/${encodeURIComponent(ORDERING_LANGUAGE)}/${encodeURIComponent(ORDERING_PROJECT)}`;
const url = new URL(`${base}/orders`);
url.search = new URLSearchParams({
  orderBy: '-id', page: '1', page_size: '5', mode: 'dashboard',
}).toString();
const response = await fetch(url, {
  headers: { 'X-Api-Key': ORDERING_API_KEY, Accept: 'application/json' },
});
const body = await response.json();
if (!response.ok || body.error) {
  throw new Error(`Ordering request failed (HTTP ${response.status})`);
}
const orders = body.result;

Inspect the List Orders contract for operation-specific inputs. Descending ID is the documented quickstart ordering; it does not guarantee sorting by a separate business date. An empty result can be valid. Avoid publishing customer data as setup evidence.

Pagination, fields, and filters

List support varies by operation. Check its parameters before using page (starting at 1), page_size, orderBy, params, or where. orderBy=-id means descending ID. params selects supported fields; invalid selections can return all fields, so do not rely on it as a security boundary. where is a JSON filter over declared filterable fields; inspect the resource's x-ordering-whereable schema extension rather than inventing field names or operators.

Read the response's pagination block when present before requesting the next page. Do not combine page-based pagination with legacy limit/offset/start unless the operation documents that combination. See Pagination. Check both HTTP status and the envelope's error flag. For 429, back off and retry later rather than looping without a limit.

MCP read/write permissions and REST changes

MCP setup connects an AI client with a separate personal key. Start with read: discover an operation with search_operations, inspect it with describe_operation, and call read_operation. Only a write key exposes write_operation, and only for the supported catalog and fields. Neither scope grants arbitrary REST access.

There is no implicit approval to change real data. Before a write, identify the project, target, method and exact changes, and obtain the user's explicit confirmation. With the quickstart, non-GET REST calls require that confirmation before using ./ordering api --yes. After an uncertain write result, read the target before retrying. Revoking a REST API key and revoking an MCP key are separate operations.