API conventions

AISafe REST endpoints share a set of cross-cutting rules: base URLs, authentication, pagination, error handling, rate limits, and identifier formats. For per-endpoint reference, see the API Reference.

Base URL

Environment	Base URL
Production	https://api.aisafe.io

Routes live under /api/v1/. The v1 namespace is a content freeze. Additive changes (new optional fields, new endpoints, new enum values on responses) stay backwards-compatible. Breaking changes bump the version.

curl https://api.aisafe.io/api/v1/assessments \
  -H "Authorization: Bearer $AISAFE_API_KEY"

Authentication

API requests need a Bearer token in the Authorization header:

Authorization: Bearer sk-ais-xxxxxxxxxxxxxxxxxxxx

AISafe supports two bearer flavors:

• API keys carry the prefix sk-ais- and scope per key. Each key carries an explicit scope list (e.g. assessments:create, findings:read). A key missing the required scope for an endpoint returns 403.
• Session JWT: the login/OAuth flows issue a JWT, carried in an httpOnly cookie for browsers or in the header for programmatic clients.

See Authentication for full details on obtaining and using API keys.

Identifiers

AISafe uses two families of identifiers:

Customer-visible IDs: hyphenated uppercase

Organizations, Assessments, Findings, and Reports carry human-readable IDs of the form AIS-{ORG}-{APP}[-{NNN}]:

Resource	Format	Example
Assessment	AIS-{ORG}-{CODE}	AIS-ACME-TLP
Finding	AIS-{ORG}-{ASSESSMENT}-{NNN}	AIS-ACME-TLP-001

These IDs are immutable, appear in URLs, reports, and exports, and are safe to share in support tickets.

Opaque IDs: prefixed tokens

Other resources (users, teams, API keys, webhook subscriptions, etc.) use short opaque identifiers with a prefix (e.g. user_, team_, apikey_, webhook_).

Pagination

List endpoints use cursor-based pagination. The response envelope includes:

{
  "items": [...],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8,
  "next_cursor": "eyJ...",
  "has_total": true
}

• next_cursor: pass this as the cursor query parameter to fetch the next page. If absent, there are no more results.
• page_size controls the number of items per page (capped per endpoint).
• has_total indicates whether the total field is accurate. Some endpoints skip the expensive COUNT query for performance.

Inbound VCS webhook delivery logs

VCS webhook delivery logs help diagnose why a push or pull request did or did not trigger project automation. Delivery rows expose only non-secret fields: provider, event type, repository, commit SHA, PR number or branch, processing status, ignored reason, and timestamps.

Endpoint	Scope
GET /api/v1/projects/{id}/webhook-deliveries	Project members can list recent deliveries for the project's bound VCS repository. Missing or foreign projects return 404.
GET /api/v1/integrations/vcs/connections/{connection_id}/webhook-deliveries	Organization members who can view the VCS connection can list recent deliveries for that connection, including events that did not match a project.

Both endpoints are newest-first and cursor paginated. Use limit and cursor; optional filters include status, event_kind, and ignored_reason.

Rate limiting

AISafe enforces rate limits using sliding windows keyed on the authenticated principal (user ID or API key owner). Exceeding the limit produces:

• The response status is 429 Too Many Requests.
• The response includes a Retry-After header (in seconds). You must honor this before retrying.

# Example: rate-limited response
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{"detail": "Rate limit exceeded. Retry after 30s."}

Strict input validation

API request bodies use strict validation. Sending an unknown field returns 422 with a validation error. The API rejects typos and blocks injection of server-managed fields. Send only the fields documented for the endpoint you are calling.

Response status codes

Status	Meaning
200	Success
400	Malformed input or business-rule validation failure
401	Missing, expired, or invalid credentials
403	Authenticated but not authorized (role too low or scope missing)
404	Resource not found (or the API collapses cross-organization access to not-found)
409	State conflict (e.g. resource cannot transition from current state)
422	Semantic validation failure
429	Rate-limited: check Retry-After header
500	Unexpected server error

See Errors for the full status code reference and handling guidance.

Related

• Authentication: API keys, scopes, and session JWTs
• Errors: error envelope and status code reference
• Webhooks: outbound webhook events and signing
• API Reference: per-endpoint documentation