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. For heartbeat-enabled claims, this also records a claim heartbeat.

POST /v1/work/run/heartbeat

Record that an active claim is still owned by the agent. SDK and MCP use this for lost-claim recovery; heartbeats are non-billable telemetry.

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/events?limit=50&offset=0

Read the normalized coordination timeline across claim events, file working-set events, and work API activity. Filter by resource_type/resource_key, resource_id, claim_id, agent_id, or event_type.

GET /v1/work/claims/:claim_id/events

Thin event timeline alias for one claim. Use it when an agent or dashboard needs the history behind one run.

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/:resource_id/events

Thin event timeline alias for one protected resource.

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. Heartbeats are logged for visibility but do not consume monthly coordination API-call quota. 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 or heartbeat was called for a claim that is already terminal. Treat as success for cleanup.

lost

A heartbeat-enabled claim stopped reporting heartbeats and Availsync marked it terminal so the resource can be claimed again.

plan_limit_reached

HTTP 402. The workspace hit a plan limit such as agents, protected resources, active claims, or monthly coordination API calls. MCP and claim heartbeats are excluded from this monthly quota.

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,
  "heartbeat_timeout_seconds": 300,
  "reason": "scheduled Codex run"
}

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

Claim heartbeat

POST /v1/work/run/heartbeat
{
  "claim_id": "CLAIM_ID",
  "client_name": "@availsync/node"
}

200 OK
{
  "action": "heartbeat_recorded",
  "claim": {
    "id": "CLAIM_ID",
    "last_heartbeat_at": "2026-05-27T10:00:00.000Z",
    "heartbeat_timeout_seconds": 300
  }
}

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" }
}

Work event timeline

GET /v1/work/events?resource_type=repo&resource_key=owner%2Frepo&limit=50

200 OK
{
  "events": [
    {
      "source": "work_file_claim_events",
      "event_type": "blocked",
      "claim_id": "CLAIM_ID",
      "resource_type": "repo",
      "resource_key": "owner/repo",
      "path": "frontend/app/page.tsx",
      "mode": "edit"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 1,
    "total": 1,
    "has_more": false
  }
}

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"]
}