API reference

Availsync v1 API reference.

Use the Node SDK or MCP package for most pilots. Use the REST API directly when you need to integrate another runtime, language, or workflow engine.

For coding agents and automations, use /v1/work/run/start, /extend, and /finish first. The lower-level /v1/work/check and/v1/work/claim endpoints are for custom raw claim clients.

Work claims protect repos, projects, and file working sets. Holds protect availability or booking windows. Coding agents should normally use agent_type: genericand rely on explicit numeric priority for arbitration.

Work claims are immediate-start guardrails. start_at may only be a few minutes in the future to absorb clock skew. Use holds/availability for future booking windows.

Node SDK Quickstart Reliability

Authentication

Agent calls use Authorization: Bearer API_KEY. Workspace dashboard calls use the login session cookie. Raw API keys are shown once at create or rotation time, then never returned again.

Authorization: Bearer AVAILSYNC_API_KEY
Content-Type: application/json
Idempotency-Key: optional-stable-key

Automation guardrail

Agent API key or workspace session

POST /v1/work/run/start

Start a guarded run. Returns proceed or skip_run. In observe mode it proceeds and may include shadow_decision.

POST /v1/work/run/working-set

Declare the files an active run is currently touching. Returns updated, partial_proceed, or HTTP 409 with blocked.

POST /v1/work/run/extend

Extend an active claim lease while the agent is still working.

POST /v1/work/run/finish

Release a run claim. Safe to call more than once.

Lower-level work coordination

Agent API key or workspace session

POST /v1/work/check

Preview whether a repo or project resource is available. Does not mutate claims.

POST /v1/work/claim

Legacy low-level claim endpoint. New automations should use /v1/work/run/start. Supports Idempotency-Key and returns deprecation headers.

POST /v1/work/claims/:claim_id/extend

Extend a specific claim.

DELETE /v1/work/claims/:claim_id

Release a specific claim.

GET /v1/work/claims/:claim_id

Fetch one claim by exact id inside the current workspace. Agent keys may use this to poll a blocking claim they were shown.

GET /v1/work/claims?limit=100&offset=0

List current and recent claims with pagination. Agent keys only list their own claims. Active claims include current working_set file claims.

GET /v1/work/resources?limit=100&offset=0

List protected resources with active claim counts and pagination. Limit is capped to avoid unbounded responses.

Activity and value

Workspace session unless noted

GET /v1/activity

List runtime traffic metadata. Workspace users can filter by agent, status, type, and date.

POST /v1/activity/usage

Agent-key endpoint for reporting optional token usage or external run metadata.

GET /v1/value/health

Dashboard value summary and agent health for the current workspace.

Billing and setup

Workspace session

GET /v1/billing/status

Current plan, limits, usage, and upgrade hints.

POST /v1/orgs/:org_id/agents/:agent_id/test-connection

Read-only setup readiness check for one agent.

POST /v1/orgs/:org_id/agents/:agent_id/setup-test

Dashboard-run validation flow. Does not require the raw API key.

MCP

Agent API key

POST /v1/mcp/heartbeat

MCP clients use this to report online status. SDK and REST traffic use last_seen_at instead.

Common response actions

proceed

The agent can run. A claim may exist in enforce mode; observe mode can proceed without a claim.

partial_proceed

A working-set update claimed some requested files but blocked others that another active run is editing or deleting.

blocked

HTTP 409 from working-set. No requested edit/delete paths were claimable because another active run owns them.

skip_run

Another active claim has priority. Scheduled jobs should exit cleanly with the reason.

already_finished

Finish was called for a claim that is already released or expired. Treat as success.

plan_limit_reached

HTTP 402. The workspace hit a plan limit such as agents, protected resources, active claims, or monthly API calls.

Failure policy

The API returns structured errors with error, optional message, and request_id. The SDK throws for network and API failures so your automation can choose fail-closed in enforce mode or fail-open in observe mode. The Node SDK uses a 30 second default timeout and also accepts request-level AbortSignal values when a caller needs stricter cancellation.

Read reliability guidance

Launch-critical examples

Start a guarded run

POST /v1/work/run/start
{
  "agent_id": "AGENT_ID",
  "resource_type": "repo",
  "resource_key": "owner/repo",
  "duration_minutes": 45,
  "reason": "scheduled Codex run"
}

200 OK
{
  "action": "proceed",
  "claim": { "id": "CLAIM_ID", "expires_at": "..." },
  "retry_after": null
}

Blocked run

200 OK
{
  "action": "skip_run",
  "reason": "Another active work claim has priority",
  "retry_after": "2026-05-22T10:30:00.000Z",
  "blocking_claim": { "id": "CLAIM_ID" }
}

Working set blocked

POST /v1/work/run/working-set
{
  "claim_id": "CLAIM_ID",
  "mode": "edit",
  "paths": ["frontend/app/page.tsx"]
}

409 Conflict
{
  "action": "blocked",
  "blocked_paths": ["frontend/app/page.tsx"]
}