Align Public API v1
The Align Public API lets you read and write Align data from your own systems: projects, entries, comments, attachments, releases, time entries, users, project members, wiki pages and webhook subscriptions. You can also read audit events, search, agreements, report snapshots and release evidence packages.
The endpoint pages in this section are generated from the OpenAPI specification. You can read them without an API key.
Basics
Base URL: https://app.alignsoft.us/api/v1
Authentication: send an API key in either header:
Authorization: Bearer <key>X-API-Key: <key>
You create keys in Align, in Settings → Developer → API Keys. Admins create organisation-scoped keys; managers, developers, tech leads and DevOps engineers create keys restricted to one project. Each key also carries a list of permissions. See API Keys and Authorization & Scopes.
The Public API must be turned on for the organisation (the Public Developer API v1 switch on the Developer page). When it is off, requests return 403 feature_disabled.
Requests: send JSON with Content-Type: application/json. Request bodies are limited to 100 KB.
Rate limits
Each key may make 600 requests per minute (sliding window). Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). Over the limit, Align returns 429 with reason rate_limit and a Retry-After header in seconds.
Pagination
Most list endpoints accept page (from 1) and pageSize (default 25, maximum 100), and respond with:
{ "data": [], "page": 1, "pageSize": 25, "total": 0 }
total counts every matching item. A few list endpoints (wiki pages, webhooks, search, agreements, report snapshots) return all items in one response with the same shape. See Reconciliation for a loop that handles both.
Idempotency
These create endpoints accept an optional Idempotency-Key header: POST /projects, POST /projects/{id}/entries, POST /entries/{id}/comments, POST /entries/{id}/attachments, POST /projects/{id}/releases, POST /webhooks, POST /projects/{id}/time-entries, POST /integration/time-entries, POST /projects/{id}/wiki-pages, POST /users/invite and POST /users/bulk-invite.
If you repeat a request with the same API key, method, path and Idempotency-Key within 24 hours, Align returns the first response again, with the header Idempotent-Replay: true, instead of repeating the action. Replays are remembered per server instance, so treat the header as protection against quick retries, not as a permanent guarantee. For a durable guarantee, use externalRef where an endpoint offers it.
Endpoints
| Area | Endpoints |
|---|---|
| Identity | GET /me |
| Projects | GET, POST /projects; GET, PATCH, DELETE /projects/{id} |
| Entries | GET, POST /projects/{id}/entries; GET, PATCH, DELETE /entries/{id} |
| Comments | GET, POST /entries/{id}/comments; PATCH, DELETE /comments/{id} |
| Attachments | GET, POST /entries/{id}/attachments; DELETE /attachments/{id} |
| Releases | GET, POST /projects/{id}/releases; GET, PATCH, DELETE /releases/{id}; GET /releases/{id}/evidence |
| Users | GET /users; POST /users/invite; POST /users/bulk-invite; GET, PATCH /users/{id} |
| Project members | GET, POST /projects/{id}/members; PATCH, DELETE /projects/{id}/members/{userId} |
| Time tracking | GET, POST /projects/{id}/time-entries; GET, PATCH, DELETE /time-entries/{id}; POST /time-entries/{id}/submit, /approve, /reject, /unlock; GET /projects/{id}/time-summary; GET /projects/{id}/cost-summary |
| Integrations | GET /integration-links; DELETE /integration-links/{id}; POST /integration/time-entries; GET /integration/time-entries/{id} |
| Webhooks | GET, POST /webhooks; GET, PATCH, DELETE /webhooks/{id}; POST /webhooks/{id}/test |
| Wiki | GET, POST /projects/{id}/wiki-pages; GET, PATCH, DELETE /wiki-pages/{id} |
| Read-only | GET /audit-events; GET /search; GET /projects/{id}/agreements; GET /projects/{id}/snapshots |
Entry status is one of open, assigned, in_progress, blocked, testing, deployed, done or solved.
OpenAPI specification
The full OpenAPI 3.1 specification is at https://app.alignsoft.us/api/v1/openapi.json. You can import it into an API client such as Postman, Insomnia or Bruno. The OpenAPI tab of Settings → Developer has Open openapi.json and a download button.
Quick start
# Check your key
curl https://app.alignsoft.us/api/v1/me \
-H "Authorization: Bearer ako_your_key_here"
# List projects (organisation-scoped key)
curl https://app.alignsoft.us/api/v1/projects \
-H "Authorization: Bearer ako_your_key_here"
# Create an entry
curl -X POST https://app.alignsoft.us/api/v1/projects/<id>/entries \
-H "Authorization: Bearer ako_your_key_here" \
-H "Content-Type: application/json" \
-d '{"title": "Login bug on mobile", "type": "bug_report", "priority": "high"}'
Errors
Errors use this envelope, sometimes with a details field:
{ "reason": "not_found", "message": "Project not found." }
| HTTP | reason | Meaning |
|---|---|---|
| 400 | validation_error | The body or a parameter failed validation; details lists the problems |
| 401 | missing_key | No API key header |
| 401 | invalid_key | Key not recognised |
| 401 | key_revoked | Key revoked |
| 401 | key_expired | Key expired |
| 402 | plan_limit | The organisation's plan limit is reached |
| 402 | feature_disabled | Time tracking is off for the organisation |
| 403 | feature_disabled | The Public API is off for the organisation |
| 403 | forbidden | The key lacks the permission, or its creator lacks the role |
| 403 | scope_violation | A project-scoped key went outside its project |
| 404 | not_found | The resource does not exist or is not visible to the key; also returned for unknown /api/v1 paths |
| 409 | status_conflict | The record's current status does not allow the action |
| 422 | various, for example user_not_found, entry_not_found, invite_failed | A referenced record does not exist or does not belong to the organisation |
| 423 | suspended | The organisation is suspended for billing |
| 429 | rate_limit | Rate limit exceeded; see Retry-After |
| 500 | internal_error | Server error |
A few responses use a different shape: an unknown webhook event name returns { "error": "unknown_event_names", "invalid": [...] }, and an endpoint that needs the Illumera add-on returns { "error": "addon_required", "addon": "illumera" }. The full list is in Authorization & Scopes.
See the API Changelog for recent changes and the MCP Integration page for connecting AI assistants.