Run a tool or a program - Spacefast Docs
Run a tool or a program
The one execution primitive: a single tool call and a code program are the same operation, with one id space, one status machine, and one resume. A run that fails answers 200 with the failure embedded — the request succeeded, the run did not. Retrying with the same idempotencyKey returns the original run and answers 200 instead of 201.
POST /v1/connectors/runs
Authorization
Authorization Bearer token · header required
Authorization: Bearer <token> with an API key (sfa_ prefix), an OAuth access token, a session token, or a Space machine credential (sfm_ prefix).
or
Authorization OAuth2 access token · header required
OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.
Scopes: connectors:execute
Query parameters
team string
min length 1 · max length 255
Request body
required application/json
input object required
One call, or a program that makes many. Same endpoint either way.
Show properties
One of:
- object
kind string required
address string required
<connectionId>/<tool>, straight off a tool listing.
min length 1 · max length 512
args object
Arguments, validated against the tool's own input schema.
default: {}
- object
kind string required
code string required
A program run in the sandbox. It may call any tool the calling credential is granted.
min length 1 · max length 200000
waitMs integer
How long to hold the request waiting for a terminal status before answering running.
min 0 · max 120000
idempotencyKey string
Retry with the same key to get the original run back (200, not 201) instead of running it twice.
min length 1 · max length 320
unattendedApprovals string
What to do when a call needs approval and nobody is watching: park it for a person, or fail fast.
default: "park"
Allowed: park, deny
Responses
200 Response for status 200
$schema string
Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.
data object required
One execution. A tool call and a code program are the same resource.
Show properties
One of:
- object
id string required
Run id (cxr_).
input object required
What the run was asked to do, without echoing arguments that may carry customer data.
Show properties
kind string required
tool is one call; code is a program that may make many. Same endpoint, same id space, same resume.
Allowed: tool, code
address string | any required
Tool address for a tool run; null for a code program.
Any of:
- string
digest string required
Content digest of the submitted input, so a retry can be recognized without replaying it.
usage object required
What this run has spent. Budgets are enforced against these numbers.
Show properties
toolCalls integer required
Tool calls made so far.
min -9007199254740991 · max 9007199254740991
egressBytes integer required
Bytes read from third-party APIs so far.
min -9007199254740991 · max 9007199254740991
durationMs integer required
Wall-clock time spent executing so far.
min -9007199254740991 · max 9007199254740991
createdAt string
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
status string required
Still executing. Poll the run, or submit the next one with a longer waitMs.
object
id string required
Run id (cxr_).
input object required
What the run was asked to do, without echoing arguments that may carry customer data.
Show properties
kind string required
tool is one call; code is a program that may make many. Same endpoint, same id space, same resume.
Allowed: tool, code
address string | any required
Tool address for a tool run; null for a code program.
Any of:
- string
digest string required
Content digest of the submitted input, so a retry can be recognized without replaying it.
usage object required
What this run has spent. Budgets are enforced against these numbers.
Show properties
toolCalls integer required
Tool calls made so far.
min -9007199254740991 · max 9007199254740991
egressBytes integer required
Bytes read from third-party APIs so far.
min -9007199254740991 · max 9007199254740991
durationMs integer required
Wall-clock time spent executing so far.
min -9007199254740991 · max 9007199254740991
createdAt string
status string required
completedAt string
result any required
Whatever the tool or program returned.
object
id string required
Run id (cxr_).
input object required
What the run was asked to do, without echoing arguments that may carry customer data.
Show properties
kind string required
tool is one call; code is a program that may make many. Same endpoint, same id space, same resume.
Allowed: tool, code
address string | any required
Tool address for a tool run; null for a code program.
Any of:
- string
digest string required
Content digest of the submitted input, so a retry can be recognized without replaying it.
usage object required
What this run has spent. Budgets are enforced against these numbers.
Show properties
toolCalls integer required
Tool calls made so far.
min -9007199254740991 · max 9007199254740991
egressBytes integer required
Bytes read from third-party APIs so far.
min -9007199254740991 · max 9007199254740991
durationMs integer required
Wall-clock time spent executing so far.
min -9007199254740991 · max 9007199254740991
createdAt string
status string required
completedAt string
default Problem details (RFC 9457). Any 4xx/5xx response is one application/problem+json document.
$schema string
Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.
type string required
URL of the documentation page for this error. Derived from code.
title string required
Human-readable name of the error type. Derived from code.
status integer required
HTTP status of the response, repeated in the body.
min -9007199254740991 · max 9007199254740991
detail string required
What went wrong in this request.
code string required
Stable snake_case error code. Match on this, not on detail.
pointer string
RFC 6901 JSON Pointer to the request field or batch entry that failed, for example /files/37/path. Present on validation failures.
details object
Machine-readable context keyed by the error code.
suggestions string[]
Recovery steps safe to show to a person.
next string[]
Commands or API requests to run next, usable as written.
requestId string required
ID of this request, from the X-Request-Id header or generated. Quote it when contacting support.
Try it
Server
Base URL https://api.spacefast.com
Custom base URL
Overrides the selected server when set.
Authorization
Bearer token
Remember on this device
Include my values in samples
Parameters
team query
Body
application/json
input string* One call, or a program that makes many. Same endpoint either way.
waitMs integer How long to hold the request waiting for a terminal status before answering running.
idempotencyKey string Retry with the same key to get the original run back (200, not 201) instead of running it twice.
unattendedApprovals string — park deny What to do when a call needs approval and nobody is watching: park it for a person or fail fast.