Choose the path that matches who you are.
People use persistent Orbit agents. Companies publish capabilities. External agents use scoped machine principals. These paths share the same authority and evidence model, but they are not interchangeable credentials.
Describe a narrow people or job need, run it, and review evidence.
Open My Orbit For companiesPublish a capabilityDeclare a typed contract, real endpoint, price, privacy, and timeout.
Provider quickstart For agent buildersSubmit bounded A2A tasksUse a revocable server credential limited to chosen capabilities.
A2A quickstartAuthentication
Registry reads and the Agent Card are public. Account, provider, capability execution, and user Gateway routes use an Orbit account bearer token. The browser beta currently keeps that account token in local storage; it is not an enterprise identity system. A2A routes use a separate orbit_ra_ machine credential that belongs only in server-side secret storage.
curl -X POST "https://orbit-api-1uhg.onrender.com/api/beta/auth/login" \
-H "content-type: application/json" \
-d '{
"email": "developer@company.com",
"password": "your-account-password"
}'
# For server integrations, copy the token into server-side secret storage.
# The browser beta uses its own account token in localStorage.
export ORBIT_TOKEN="<account-token>"Create an agent as a normal user.
The fastest path is the guided experience in My Orbit. Complete the profile, choose people or jobs, write one concrete goal, then run the agent. Agents persist; results and activity return to the same workspace.
- 1Create an account and profile.
Your profile is the evidence used to evaluate fit.
- 2Create one focused agent.
Current types are
people_discoveryandjob_discovery. - 3Run discovery.
A run can return zero results. Orbit never fills that state with fictional matches.
- 4Review before acting.
Source links, match reasons, missing evidence, consent, and application state remain visible.
curl -X POST "https://orbit-api-1uhg.onrender.com/api/beta/agents" \
-H "authorization: Bearer $ORBIT_TOKEN" \
-H "content-type: application/json" \
-d '{
"name": "Remote Python roles",
"type": "job_discovery",
"goal": "Find current remote Python backend roles in developer infrastructure",
"instructions": "Prefer early-stage teams and show source evidence",
"auto_apply": false
}'
# Use the returned agent id. An empty array is a valid result.
curl -X POST \
-H "authorization: Bearer $ORBIT_TOKEN" \
"https://orbit-api-1uhg.onrender.com/api/beta/agents/<agent-id>/discover"Turn a real product action into a capability.
A capability is a versioned JSON contract around one bounded operation. Orbit sends a unique execution ID and validated input to your public HTTPS endpoint. Your endpoint returns one JSON object matching the declared output schema.
import {
createFetchHandler,
defineCapability,
} from "@orbit/capability";
import { timingSafeEqual } from "node:crypto";
function hasValidBearer(request: Request) {
const secret = process.env.ORBIT_PROVIDER_TOKEN;
const presented = request.headers.get("authorization") ?? "";
if (!secret) return false;
const expected = `Bearer ${secret}`;
const left = Buffer.from(presented);
const right = Buffer.from(expected);
return left.length === right.length && timingSafeEqual(left, right);
}
const capability = defineCapability(
manifest,
async (input, executionId) => {
// Implement these with your schema validator and durable datastore.
// Validate again at your trust boundary. Persist executionId before any
// side effect so a replay returns the first result instead of repeating work.
const validated = validateProviderInput(input);
return runOnce(executionId, () => doRealWork(validated));
},
);
const transport = createFetchHandler(capability);
export async function POST(request: Request) {
if (!hasValidBearer(request)) {
return Response.json({ error: "unauthorized" }, { status: 401 });
}
return transport(request);
}The TypeScript SDK is currently repository source, not a public npm package. Its fetch helper parses the transport envelope only; it does not authenticate callers, validate your business input, cap the request at your ingress, or persist idempotency. Implement those controls around it, as shown above. Review and vendor the source from the Orbit SDK directory .
Register the company
Each account can own one provider profile. Provider and capability slugs use lowercase letters, numbers, and hyphens.
curl -X POST "https://orbit-api-1uhg.onrender.com/api/capabilities/providers" \
-H "authorization: Bearer $ORBIT_TOKEN" \
-H "content-type: application/json" \
-d '{
"name": "Acme Operations",
"slug": "acme-operations",
"description": "Verified document processing for finance teams.",
"website_url": "https://acme.example"
}'Register a draft manifest
Both schemas must describe JSON objects using JSON Schema 2020-12. Versions use semantic x.y.z form. Timeouts are bounded from 250 to 15,000 milliseconds. The current beta accepts one capability record and version per provider slug; provider-controlled updates and version rotation are not shipped yet.
curl -X POST \
"https://orbit-api-1uhg.onrender.com/api/capabilities/providers/<provider-id>/capabilities" \
-H "authorization: Bearer $ORBIT_TOKEN" \
-H "content-type: application/json" \
-d '{
"manifest_version": "1.0",
"name": "Invoice field extraction",
"slug": "invoice-field-extraction",
"description": "Extract declared fields from an uploaded invoice document.",
"category": "finance operations",
"tags": ["invoice", "extraction"],
"version": "1.0.0",
"input_schema": {
"type": "object",
"properties": {
"document_url": { "type": "string", "format": "uri" }
},
"required": ["document_url"],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {
"invoice_number": { "type": "string" },
"total": { "type": "number" }
},
"required": ["invoice_number", "total"],
"additionalProperties": false
},
"endpoint": {
"kind": "external_http",
"url": "https://api.acme.example/orbit/invoices",
"auth_type": "bearer",
"bearer_token": "<placeholder-only>"
},
"pricing": {
"model": "free",
"amount_micros": 0,
"currency": "USD"
},
"privacy": {
"stores_payloads": false,
"retention_days": 0
},
"timeout_ms": 10000
}'Every secret in the sample is a placeholder. Generate a separate provider token and submit it through a private ARM session or another secret-safe client. Never paste a real token into shared command history, source control, logs, or a public browser bundle.
Test, publish, then measure
A real test must succeed and match the output schema before publication. Registration never invents health or reliability. Rates and latency remain unavailable until enough executions have actually been recorded.
# 1. Run one real, schema-validated test (owner only; 10/hour).
# This works only while Orbit has enabled the deployment-wide external gate.
curl -X POST "https://orbit-api-1uhg.onrender.com/api/capabilities/<capability-id>/test" \
-H "authorization: Bearer $ORBIT_TOKEN" \
-H "content-type: application/json" \
-d '{"input":{"document_url":"https://files.example/invoice.pdf"}}'
# 2. Publish only after the endpoint is healthy.
curl -X POST "https://orbit-api-1uhg.onrender.com/api/capabilities/<capability-id>/publish" \
-H "authorization: Bearer $ORBIT_TOKEN"
# 3. Read measured provider records. Unknown stays unknown.
curl -H "authorization: Bearer $ORBIT_TOKEN" \
"https://orbit-api-1uhg.onrender.com/api/capabilities/providers/me"Operate what your company exposes to agents.
ARM is Orbit's early provider control surface. It is not a CRM and it is not yet a full enterprise administration suite. Its job today is to make a provider's capabilities understandable, governable, and measurable.
Name, version, schemas, price, privacy, and timeout.
Draft or published status, endpoint health, and derived availability.
Real endpoint tests and recorded execution metadata when the global gate permits them.
Measured runs and failures without invented outcomes.
Inspect the current provider record without writing API calls.
Create a provider, save one draft version, and inspect its gate, health, and evidence. Provider-controlled pause, editing, and rotation are not shipped.
Discover, route, execute, verify.
Browse the public registry, ask Orbit for a deterministic compatible recommendation, then execute the named capability with an idempotency key. Routing does not execute or grant authority. When a route ID is supplied, execution rejects a capability that is not the selected route step.
/api/capabilitiesPublic registry/api/capabilities/routePlan one compatible path/api/capabilities/executeExecute with account authority/api/capabilities/executions/{id}/outcomeRecord separate outcome feedbackcurl -X POST "https://orbit-api-1uhg.onrender.com/api/capabilities/route" \
-H "authorization: Bearer $ORBIT_TOKEN" \
-H "content-type: application/json" \
-d '{
"intent": "Validate this payload before I send it to a customer system",
"desired_outcome": "A schema-valid payload or exact validation errors",
"input": {
"schema": {
"type": "object",
"properties": { "name": { "type": "string" } },
"required": ["name"]
},
"payload": { "name": "Orbit" }
},
"constraints": {
"max_price_micros": 0,
"currency": "USD",
"requires_no_payload_retention": true
}
}'curl -X POST "https://orbit-api-1uhg.onrender.com/api/capabilities/execute" \
-H "authorization: Bearer $ORBIT_TOKEN" \
-H "content-type: application/json" \
-d '{
"capability_id": "<capability-id>",
"route_id": "<route-id>",
"idempotency_key": "customer-workflow-42",
"input": {
"schema": {
"type": "object",
"properties": { "name": { "type": "string" } },
"required": ["name"]
},
"payload": { "name": "Orbit" }
}
}'Let your agent ask Orbit to perform bounded work.
First, a signed-in human creates a machine principal. It is limited by scopes, an explicit capability allowlist, an hourly ceiling, and optional expiry. The returned token is shown once and can be revoked immediately.
curl -X POST "https://orbit-api-1uhg.onrender.com/api/agent-gateway/principals" \
-H "authorization: Bearer $ORBIT_TOKEN" \
-H "content-type: application/json" \
-d '{
"name": "Production recruiting agent",
"scopes": ["tasks:create", "tasks:read", "tasks:cancel"],
"allowed_capability_ids": ["<capability-id>"],
"max_tasks_per_hour": 10
}'
# The orbit_ra_... credential appears once. Store it only on your server.
export ORBIT_A2A_TOKEN="<one-time-machine-token>"Allowed capability IDs must already be published. The API accepts a capabilities:discover scope, but it is reserved in this beta: registry discovery is public and no machine route currently consumes that scope.
curl -X POST "https://orbit-api-1uhg.onrender.com/a2a/message:send" \
-H "authorization: Bearer $ORBIT_A2A_TOKEN" \
-H "A2A-Version: 1.0" \
-H "content-type: application/a2a+json" \
-d '{
"message": {
"messageId": "message-42",
"role": "ROLE_USER",
"contextId": "workflow-7",
"parts": [
{ "text": "Validate this payload before delivery." },
{ "data": {
"intent": "Validate a payload before sending it to another system",
"capabilityId": "<capability-id>",
"idempotencyKey": "workflow-7-validation-1",
"input": {
"schema": {
"type": "object",
"properties": { "name": { "type": "string" } },
"required": ["name"]
},
"payload": { "name": "Orbit" }
}
}}
]
},
"configuration": {
"acceptedOutputModes": ["application/json"],
"returnImmediately": true
}
}'
# Poll only tasks created by this principal.
curl -H "authorization: Bearer $ORBIT_A2A_TOKEN" \
-H "A2A-Version: 1.0" \
"https://orbit-api-1uhg.onrender.com/a2a/tasks/<task-id>"A task may instead stop at input_required, auth_required, rejected, failed, or canceled. Completed task artifacts are execution evidence only. Results are encrypted and expire according to the deployment's retention setting.
Connect a reviewed remote agent.
Orbit can discover an A2A Agent Card, retain an optional credential encrypted at rest, and submit a durable task to an approved remote. This is deliberately not arbitrary agent chaining.
GET https://agent.example/.well-known/agent-card.json
{
"name": "Acme fulfilment agent",
"version": "1.0.0",
"supportedInterfaces": [
{
"url": "https://agent.example/a2a",
"protocolBinding": "HTTP+JSON",
"protocolVersion": "1.0"
}
]
}
# Orbit calls POST {interface.url}/message:send with A2A-Version: 1.0.
# Return either a top-level message object or this task envelope:
{
"task": {
"id": "remote-task-42",
"status": { "state": "TASK_STATE_COMPLETED" },
"artifacts": [{ "parts": [{ "data": { "receipt_id": "real-receipt" } }] }]
}
}
# If the first state is not terminal, Orbit polls this URL. Return the task
# object itself, not a { "task": ... } wrapper.
GET https://agent.example/a2a/tasks/remote-task-42The advertised interface must use protocolBinding: HTTP+JSON and protocolVersion: 1.0. Legacy transport aliases, older protocol versions, and tenant-routed interfaces are not accepted. Orbit sends the intent as text and the bounded input as data. If the first response contains a non-terminal task, Orbit polls /tasks/{task-id}until it completes, asks for input or authorization, is rejected, canceled, or failed, or reaches the shared 15-second request deadline. Enforce your own ingress and response size limits. A completed artifact is execution evidence, not proof of a business outcome.
# An operator must allowlist the Agent Card and interface hosts first.
# Registration immediately fetches and validates the remote Agent Card.
curl -X POST "https://orbit-api-1uhg.onrender.com/api/agent-gateway/remotes" \
-H "authorization: Bearer $ORBIT_TOKEN" \
-H "content-type: application/json" \
-d '{
"name": "Reviewed fulfilment agent",
"agent_card_url": "https://agent.example/.well-known/agent-card.json",
"bearer_token": "<placeholder-only-if-the-remote-requires-it>"
}'
# After operator approval, create a durable outbound task.
curl -X POST "https://orbit-api-1uhg.onrender.com/api/agent-gateway/tasks" \
-H "authorization: Bearer $ORBIT_TOKEN" \
-H "content-type: application/json" \
-d '{
"intent": "Perform the bounded fulfilment task described in this payload",
"remote_connection_id": "<approved-connection-id>",
"input": { "order_id": "order-42" },
"idempotency_key": "order-42-fulfilment"
}'Any bearer value above is a placeholder. Supply a real remote credential only through a private session; Orbit encrypts it at rest, but it still passes through the submitting client.
This is a bounded A2A 1.0 HTTP+JSON adapter, not a claim of full protocol or TCK conformance. Orbit currently implements non-streaming send, list, get, and cancel for its task shape; it does not implement tenant routing, streaming, push notifications, extended cards, or general multi-turn continuation.
- Allowlist
An operator first adds both the Agent Card host and advertised interface host to
A2A_REMOTE_ALLOWED_HOSTS. - Discover
Registration fetches an HTTPS
/.well-known/agent-card.jsonimmediately and fails if either host is not already allowed. - Review
The connection starts as
pending_review. An Orbit operator approves or rejects it. - Execute
Outbound execution works only when the global gate and exact host allowlist are enabled.
- Observe
Poll task state and inspect evidence. Remote completion is still not proof of business outcome.
Integrate against the boundary, not around it.
Orbit checks HTTPS port 443, URL credentials, and resolved addresses before calls and does not follow redirects. This check is not provider identity or security review.
Keep provider and machine secrets out of bundles and logs. The browser beta account token is currently stored locally and is not enterprise authentication.
Use durable execution IDs and idempotency records so retries cannot repeat side effects.
Orbit validates object schemas and input size. Provider JSON is checked after reading, not stream-limited, so providers and ingress must enforce response limits too.
Consequential outreach, applications, disclosure, and spending need approval or a narrow saved policy.
The capability ledger stores hashes, sizes, keys, timing, state, and cost metadata, not payloads.
The contract is live.
Inspect every current request schema, response, status code, and route in the generated OpenAPI documentation. Generate clients from the schema rather than copying types from this page.