Skip to main content
RUSTGRID
Launch RustGrid

API-first execution primitives

Build the control plane your agents need.

RustGrid exposes projects, missions, workers, runs, sequenced events, quality results, activity, repository bindings, and webhooks through explicit contracts. Integrate a worker or build a different experience without inventing a second source of operational state.

API reference Run the quickstart

Mission API mapping

Public product language. Current contract names.

RustGrid calls a structured unit of engineering work a mission. In the current API, that object maps to the /api/v1/tickets resource. Integrations should keep using the documented ticket endpoints, field names, statuses, ETags, and permissions.

Create a mission through the current ticket contract

Send either project_key or project_id. Tenant scope comes from the bearer credential; clients do not send a tenant selector header.

Product term

Mission

ticket
Create

Start a structured unit of work

POST /api/v1/tickets
Inspect

Read current state and ETag

GET /api/v1/tickets/{id}
History

Read mission activity

GET /api/v1/tickets/{id}/activity
POST /api/v1/ticketscURL
curl -sS -X POST \
  "https://app.rustgrid.com/api/v1/tickets" \
  -H "Authorization: Bearer $RG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mission-invitations-v1" \
  -d '{
    "project_key": "RGC",
    "title": "Add invitation management",
    "description": "Add resend and revoke actions.",
    "type": "task",
    "priority": "high",
    "status": "todo"
  }'

Platform primitives

Compose the workflow. Keep the boundaries visible.

Each API surface has one operational job. Use only what your integration needs, or combine them into a complete autonomous-delivery loop.

Projects

Scope people, work, and repositories

Create projects, manage membership and roles, define labels and custom fields, and inspect project backlog state.

Missions

Hold intent and workflow state

Create, search, update, assign, relate, watch, comment on, and attach files to the current ticket resource.

Runs

Represent each execution attempt

Create or claim a run, update its outcome, append steps, and inspect separate attempts for the same mission.

Workers

Expose liveness and capacity

Register tenant workers, issue or revoke worker credentials, heartbeat status, and consume worker queue state.

Quality gates

Record validation explicitly

Report running, passed, or failed results with structured checks and an optional link to the producing run.

Events

Integrate without polling everything

Replay or stream run events, subscribe to workflow webhooks, inspect deliveries, and read tenant or mission activity.

Authentication and scope

Credentials carry the boundary.

RustGrid derives tenant context from the bearer credential. Human and administrative flows can use tenant-scoped JWTs; automation uses scoped rgk_ API keys; workers use credentials bound to their tenant worker identity.

Bearer JWT

Account and workspace operations

Use the authenticated user context for operations such as project administration and API-key creation.

rgk_ API key

Scoped application automation

Choose the permissions an integration needs. The full secret is returned only once when a key is created.

Worker credential

Bound agent execution

Worker credentials authorize run claiming, event reporting, lease extension, and repository-bound execution calls.

Custom workers and agents

A concrete protocol for execution.

A worker is not a hidden callback. It registers, advertises liveness, claims work under a lease, resolves its manifest, reports progress, and closes its run through auditable API calls.

01

Register

POST /api/v1/agent-workers/register

02

Claim

POST /api/v1/agent-runs/claim-next

03

Resolve

GET /api/v1/agent-runs/{run_id}/manifest

04

Report

POST …/events and POST …/steps

Leases prevent ambiguous ownership

A claim expires unless the owning worker extends it. An active unexpired claim conflicts; an expired claim can be released before a new attempt is created.

The manifest packages execution policy

It resolves the project, mission, repository, required workflows, required permissions, and an integrity hash for the execution policy.

Events and webhooks

Choose replay, live delivery, or outbound integration.

RustGrid separates the event stream inside one run from broader webhook and activity feeds, so each consumer can use the most appropriate delivery model.

Available

Durable run-event replay

GET /api/v1/agent-runs/{run_id}/events returns events in ascending sequence order.

Available

Server-sent event stream

Resume the run stream with Last-Event-ID or after_sequence instead of assuming the connection is permanent.

Available

Webhook subscriptions

Create subscriptions, rotate signing secrets, inspect delivery attempts, and unpause a subscription after resolving a failure.

Reconnect a run streamSSE
curl -N \
  "https://app.rustgrid.com/api/v1/agent-runs/$RUN_ID/events/stream" \
  -H "Authorization: Bearer $RG_WORKER_KEY" \
  -H "Last-Event-ID: 42"

Repository and GitHub events

Keep execution access narrow and code state native.

Projects can bind repositories discovered through a GitHub App installation. A claimed worker resolves that binding through its manifest and can request a short-lived installation token restricted to the run repository.

The GitHub webhook endpoint verifies and processes pull request, review, check, workflow, and installation lifecycle events. Delivery audit records make integration behavior inspectable.

Explore GitHub integration
GET/api/v1/integrations/github/repositories
POST/api/v1/integrations/github/repositories
GET/api/v1/agent-runs/{run_id}/manifest
POST/api/v1/agent-runs/{run_id}/github-token
GET/api/v1/integrations/github/deliveries

Custom quality gates

Report the checks your delivery policy requires.

The gate result contract accepts a state, structured checks, an optional summary, and an optional run reference. Your worker or integration can translate test, build, lint, security, accessibility, or external CI output into that common mission-level record.

POST /api/v1/tickets/{id}/quality-gate-resultsJSON
{
  "run_id": "7bb4…",
  "status": "passed",
  "summary": "Required validation completed",
  "checks": [
    { "name": "typecheck", "status": "passed" },
    { "name": "unit-tests", "status": "passed" },
    { "name": "build", "status": "passed" }
  ]
}

Published contract

Start from OpenAPI, not an imagined SDK.

The current public integration surface is the HTTP API and its OpenAPI document. Use cURL directly, bring your preferred HTTP client, or generate a typed client for your language while preserving the documented field and error semantics.

Open API reference Read the quickstart
AUTHAuthorization: Bearer …
TRACEx-request-id
RETRYIdempotency-Key
WRITEIf-Match: "tickets:…:version"
SPEC/api/v1/openapi.json