Skip to main content

API Changelog

Changes to the Align Public API v1. This log is updated with every change. Breaking changes are not introduced within v1 — they ship under /api/v2. All changes listed here are additive.

Convention for contributors: add a new ## YYYY-MM-DD section at the top of this file with a brief description of the change. Reference the internal task number in parentheses where applicable.

2026-06-04​

Added — Entry deployment stage tracking (ALN-64)​

  • Entry response objects now include a deploymentStage field ("testing" | "staging" | "production" | null). The field is set automatically by the Railway deployment webhook or the GitHub deployment_status webhook when a matching entry is deployed to a tracked environment. It is read-only via the API — deploymentStage is ignored in POST /api/v1/projects/:id/entries and PATCH /api/v1/entries/:id bodies.

Added — MCP server compliance (ALN-59, ALN-60, ALN-67)​

  • GET /.well-known/oauth-protected-resource — returns RFC 9728 OAuth Protected Resource metadata. Used by MCP clients (Claude.ai, CODEX) to discover the token endpoint before connecting.
  • GET /mcp/privacy — redirects to the Align privacy policy. Required for CODEX marketplace listing.
  • All 22 MCP tools now carry OpenAPI-compatible tool annotations (title, readOnlyHint, openWorldHint, destructiveHint). Clients that support tool annotations can use these to surface safe-for-automation indicators in their UI.
  • MCP endpoints now enforce an origin allowlist and return 403 Forbidden for requests from unlisted origins.

2026-05-14​

Added — Release Evidence signing key management​

  • GET /api/settings/evidence-key — returns whether a signing key is configured and its key prefix (evk_<prefix>). Requires admin role.
  • POST /api/settings/evidence-key — generate (or rotate) the organisation-level HMAC signing key for release evidence packages. Issuing a new key automatically revokes the previous one. The full key (evk_<64hex>) is returned once; store it in your secrets manager immediately.
  • Evidence responses now include X-Align-Evidence-Signature: sha256=<hex> and X-Align-Evidence-Key-Prefix: evk_<prefix> headers when a signing key is configured.

Note: These endpoints are session-authenticated platform-settings routes (/api/settings/) — they are not part of the public v1 API and do not appear in the OpenAPI spec. They are accessible to org admins via the Align web app only.

2026-05-10​

Added — Snapshot (report) endpoints (Task #303)​

  • GET /api/v1/projects/:id/snapshots — list report snapshots for a project, paginated. Each snapshot includes narrativeSource ('ai' or 'template') and the generated summary text.

The narrativeSource field indicates whether the executive summary was produced by GPT-4.1 or fell back to the template generator (e.g. when the AI provider is unavailable or the prompt was redacted).

Note: Individual snapshot retrieval (GET /api/v1/snapshots/:id) is not yet available in the public API. Use the project list endpoint and filter client-side by id.

2026-05-07​

Added — Wiki page endpoints (Task #302)​

  • GET /api/v1/projects/:id/wiki-pages — list wiki pages for a project, paginated.
  • POST /api/v1/projects/:id/wiki-pages — create a wiki page. Required fields: title. Optional: content (Markdown).
  • GET /api/v1/wiki-pages/:id — retrieve a single wiki page with full Markdown content.
  • PATCH /api/v1/wiki-pages/:id — update title or content.
  • DELETE /api/v1/wiki-pages/:id — delete a wiki page.

2026-05-03​

Added — Agreement endpoints (Task #301)​

  • GET /api/v1/projects/:id/agreements — list agreements for a project, paginated. Returns id, title, status, and createdAt.
  • GET /api/v1/agreements/:id — retrieve a single agreement's metadata (does not return the signed document binary).

Note: Agreement creation and sending require the Dropbox Sign integration to be configured. Creating agreements via the API is not yet supported in v1.

2026-04-28​

Added — Audit event endpoints (Task #300)​

  • GET /api/v1/audit-events — list audit events across the organisation, paginated. Supports entityType, action, and actorId query filters.
  • GET /api/v1/projects/:id/audit-events — list audit events scoped to a specific project.

Audit events include actorType: 'api_key' and apiKeyId in metadata when the action was performed via an API key.

2026-04-21​

Added — User list endpoint (Task #299)​

  • GET /api/v1/users — list users in the organisation, paginated. Returns id, name, email, role, organizationId, and createdAt. Sensitive fields (password hash, MFA secrets) are excluded.
  • GET /api/v1/users/:id — retrieve a single user.

Organisation-scoped keys see all users. Project-scoped keys see only members of their scoped project.

2026-04-15​

Added — Global search endpoint​

  • GET /api/v1/search?q=<query> — search across projects, entries, releases, and wiki pages. Returns up to 25 results with type, id, title, projectId, and url fields.

2026-04-10​

Added — Outbound webhook subscriptions​

  • GET /api/v1/webhooks — list webhook subscriptions.
  • POST /api/v1/webhooks — create a subscription. hmacSecret is returned once on creation.
  • PATCH /api/v1/webhooks/:id — update destinationUrl, eventNames, enabled, or description.
  • DELETE /api/v1/webhooks/:id — delete a subscription.
  • POST /api/v1/webhooks/:id/rotate-secret — rotate the HMAC secret; new secret returned once.

2026-04-01​

Added — Release evidence endpoint​

  • GET /api/v1/releases/:id/evidence — retrieve a structured evidence package for a release, including the approval chain, quality checklists, entry summary, and GitHub evidence (commits, PRs, CI results).

2026-03-20​

Added — Core resource endpoints (initial v1 launch)​

Initial set of endpoints released:

  • GET /api/v1/me — API key identity
  • GET|POST /api/v1/projects — list and create projects
  • GET|PATCH|DELETE /api/v1/projects/:id
  • GET|POST /api/v1/projects/:id/entries — list and create entries
  • GET|PATCH|DELETE /api/v1/entries/:id
  • GET|POST /api/v1/entries/:id/comments
  • GET|DELETE /api/v1/comments/:id
  • GET /api/v1/entries/:id/attachments
  • GET|POST /api/v1/projects/:id/releases
  • GET|PATCH|DELETE /api/v1/releases/:id