REST API reference

Base URL

<api-base-url>

REST API paths are scoped to either an organization or a project. Org-scoped endpoints (organization management, listing or creating projects) use /v1/orgs/{org_id}/(e.g. /v1/orgs/{org_id}/projects). Project-scoped endpoints use /v1/orgs/{org_id}/projects/{project_id}/and require both the organization ID and project ID.

Authentication

REST API requests require one of the following authentication methods:

1. Browser session cookie — The awf_cloud_session cookie is set after signing in through the console.
2. API key bearer token — Send the API key in the Authorization header:

Authorization: Bearer <your-api-key>

When using an API key, include the following headers to specify the target organization and project. The org header is required on routes without an {org_id} path segment (e.g. GET /v1/orgs, currently reserved / 501):

X-AWF-Org-ID: <your-org-id>
X-AWF-Project-ID: <your-project-id>

Path convention

Org-scoped endpoints follow the pattern:

/v1/orgs/{org_id}/{resource}

Project-scoped endpoints follow the pattern:

/v1/orgs/{org_id}/projects/{project_id}/{resource}

For example, /v1/orgs/{org_id}/projects lists or creates projects (org-scoped), while /v1/orgs/{org_id}/projects/{project_id}/mcp accesses a project resource (project-scoped).

Error envelope

Error responses follow a structured envelope:

{
  "request_id": "req_abc123",
  "reason_code": "INSUFFICIENT_SCOPE",
  "message": "Actor lacks required scope for this action.",
  "details": {}
}

The reason_code field provides a machine-readable error code. The request_id field can be used for support inquiries.