POST /runs/dispatch
POST
/runs/dispatchAuthorization
AuthorizationBearer token · headerrequiredRequest body
requiredapplication/jsonnamestringrequiredmin length 1 · max length 64 · matches ^[a-z0-9][a-z0-9._-]*$
extensionstringrequiredmin length 1 · max length 64 · matches ^[a-zA-Z0-9][a-zA-Z0-9._-]*$
inputanydefault: {}
refstringmin length 1
Responses
200OK
runobjectrequiredShow propertiesHide properties
idstringrequiredrepoIdstringrequiredrepoNamestringrequiredextensionstringrequiredmin length 1 · max length 64 · matches ^[a-zA-Z0-9][a-zA-Z0-9._-]*$
triggerstringrequiredAllowed:
dispatchpushrecordeventdaemonstatusstringrequiredAllowed:
queuedrunningsucceededfailedcancelledactorobjectrequiredShow propertiesHide properties
kindstringrequiredAllowed:
useranonymoussystemagentmcpidstringrequiredrefstringrequiredbeforestring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anyafterstring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anycommitShastring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anycanonicalRefstringrequiredcanonicalCommitShastring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anyexecutedModuleHashstring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anycanonicalDescriptorHashstring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anycanonicalGrantHashstring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anycauseEventIdstring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anyrootEventIdstring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anycausationDepthinteger | anyrequiredShow propertiesHide properties
Any of:
integer
integerany
anyinputanyoutputanyShow propertiesHide properties
Any of:
any
anyany
anyinputSchemaobjectoutputSchemaobjectruntimestringrequiredAllowed:
workersandboxworkflowcapabilitiesstring[]requiredShow propertiesHide properties
Array of
stringAny of:
string
stringstring
stringeffectiveCapabilitiesstring[]requiredShow propertiesHide properties
Array of
stringAny of:
string
stringstring
stringtokenIdstring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anyexitCodeinteger | anyrequiredShow propertiesHide properties
Any of:
integer
integerany
anyerrorstring | anyrequiredShow propertiesHide properties
Any of:
string
stringany
anycreatedAtnumberrequiredstartedAtnumber | anyrequiredShow propertiesHide properties
Any of:
number
numberany
anyendedAtnumber | anyrequiredShow propertiesHide properties
Any of:
number
numberany
any400400
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Bad request"
dataobjectShow propertiesHide properties
issuesobject[]Show propertiesHide properties
Array of
objectpathstring | number[]Show propertiesHide properties
Array of
string | numberAny of:
string
stringnumber
numbermessagestringrequiredobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany401401
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Sign in required"
dataobjectobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany403403
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "You do not have access to this resource"
dataobjectShow propertiesHide properties
reasonstringAllowed:
not_a_memberinsufficient_rolescope_missingwrite_frozenobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany404404
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Extension not found"
dataobjectrequiredShow propertiesHide properties
namestringrequiredextensionstringrequiredrefstringobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Run not found"
dataobjectrequiredShow propertiesHide properties
idstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Invitation not found"
dataobjectrequiredShow propertiesHide properties
invitationIdstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Invite not found"
dataobjectobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "API key not found"
dataobjectrequiredShow propertiesHide properties
idstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Repo not found"
dataobjectrequiredShow propertiesHide properties
namestringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Git object not found"
dataobjectrequiredShow propertiesHide properties
namestringrequiredobjectstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Feature is not available"
dataobjectrequiredShow propertiesHide properties
featureanyrequiredobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany409409
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Extension build provenance verification failed"
dataobjectrequiredShow propertiesHide properties
namestringrequiredreasonstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Git ref already exists"
dataobjectrequiredShow propertiesHide properties
namestringrequiredrefstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Git ref is stale"
dataobjectrequiredShow propertiesHide properties
namestringrequiredrefstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Record migration blocked"
dataobjectrequiredShow propertiesHide properties
namestringrequiredreasonsstring[]requiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Repo already exists"
dataobjectrequiredShow propertiesHide properties
namestringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Cannot delete your last owned organization"
dataobjectrequiredShow propertiesHide properties
slugstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Cannot delete an organization that still owns repos"
dataobjectrequiredShow propertiesHide properties
slugstringrequiredrepoCountintegerrequiredmin 0 · max 9007199254740991
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Organization slug is already taken"
dataobjectrequiredShow propertiesHide properties
slugstringrequiredobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany410410
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Invite is no longer available"
dataobjectrequiredShow propertiesHide properties
reasonstringrequiredAllowed:
revokedexpiredexhaustedrepo_unavailableobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany413413
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Request payload exceeds the supported limit"
dataobjectrequiredShow propertiesHide properties
scopestringrequiredAllowed:
workspace_commitgit_workspace_memorylimitnumberrequiredobservednumberobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany422422
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Extension is invalid"
dataobjectrequiredShow propertiesHide properties
namestringrequiredextensionstringreasonstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Extension build failed"
dataobjectrequiredShow propertiesHide properties
namestringrequiredmessagestringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Run rejected"
dataobjectrequiredShow propertiesHide properties
idstringreasonstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Git ref update is not a fast-forward"
dataobjectrequiredShow propertiesHide properties
namestringrequiredrefstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Invalid git tree"
dataobjectrequiredShow propertiesHide properties
namestringrequiredobjectstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Invalid git parent"
dataobjectrequiredShow propertiesHide properties
namestringrequiredobjectstringrequiredobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany429429
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Too many requests"
dataobjectShow propertiesHide properties
retryAfterMsintegermin 0 · max 9007199254740991
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Quota exceeded"
dataobjectrequiredShow propertiesHide properties
scopestringrequiredAllowed:
anonorgsizelimitnumberrequiredobservednumberprojectednumberobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany502502
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Git remote write failed"
dataobjectrequiredShow propertiesHide properties
namestringrequiredrefstringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Repo import failed"
dataobjectrequiredShow propertiesHide properties
namestringrequiredobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataany503503
One of:
object
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Extension build service is unavailable"
dataobjectrequiredShow propertiesHide properties
namestringrequiredobject
definedanyrequiredcodeanyrequiredstatusanyrequiredmessagestringrequireddefault: "Repo workspace is required for this git operation"
dataobjectrequiredShow propertiesHide properties
namestringrequiredobject
definedanyrequiredcodestringrequiredstatusnumberrequiredmessagestringrequireddataanyRequest
curl -X POST "/api/v1/runs/dispatch" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"extension": "string",
"input": {},
"ref": "string"
}'const response = await fetch("/api/v1/runs/dispatch", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({
"name": "string",
"extension": "string",
"input": {},
"ref": "string"
})
});import requests
response = requests.post(
"/api/v1/runs/dispatch",
headers={
"Authorization": "Bearer YOUR_TOKEN",
"Content-Type": "application/json"
},
json={
"name": "string",
"extension": "string",
"input": {},
"ref": "string"
},
)Response
{
"run": {
"id": "string",
"repoId": "string",
"repoName": "string",
"extension": "string",
"trigger": "dispatch",
"status": "queued",
"actor": {
"kind": "user",
"id": "string"
},
"ref": "string",
"before": "string",
"after": "string",
"commitSha": "string",
"canonicalRef": "string",
"canonicalCommitSha": "string",
"executedModuleHash": "string",
"canonicalDescriptorHash": "string",
"canonicalGrantHash": "string",
"causeEventId": "string",
"rootEventId": "string",
"causationDepth": 0,
"input": "string",
"output": "string",
"inputSchema": {},
"outputSchema": {},
"runtime": "worker",
"capabilities": [
"repoRead"
],
"effectiveCapabilities": [
"repoRead"
],
"tokenId": "string",
"exitCode": 0,
"error": "string",
"createdAt": 0,
"startedAt": 0,
"endedAt": 0
}
}{
"defined": true,
"code": "BAD_REQUEST",
"status": 400,
"message": "Bad request",
"data": {
"issues": [
{
"path": [
"string"
],
"message": "string"
}
]
}
}{
"defined": true,
"code": "UNAUTHENTICATED",
"status": 401,
"message": "Sign in required",
"data": {}
}{
"defined": true,
"code": "FORBIDDEN",
"status": 403,
"message": "You do not have access to this resource",
"data": {
"reason": "not_a_member"
}
}{
"defined": true,
"code": "EXTENSION_NOT_FOUND",
"status": 404,
"message": "Extension not found",
"data": {
"name": "string",
"extension": "string",
"ref": "string"
}
}{
"defined": true,
"code": "EXTENSION_PROVENANCE",
"status": 409,
"message": "Extension build provenance verification failed",
"data": {
"name": "string",
"reason": "string"
}
}{
"defined": true,
"code": "INVITE_UNAVAILABLE",
"status": 410,
"message": "Invite is no longer available",
"data": {
"reason": "revoked"
}
}{
"defined": true,
"code": "PAYLOAD_TOO_LARGE",
"status": 413,
"message": "Request payload exceeds the supported limit",
"data": {
"scope": "workspace_commit",
"limit": 0,
"observed": 0
}
}{
"defined": true,
"code": "EXTENSION_INVALID",
"status": 422,
"message": "Extension is invalid",
"data": {
"name": "string",
"extension": "string",
"reason": "string"
}
}{
"defined": true,
"code": "TOO_MANY_REQUESTS",
"status": 429,
"message": "Too many requests",
"data": {
"retryAfterMs": 0
}
}{
"defined": true,
"code": "GIT_REMOTE_WRITE_FAILED",
"status": 502,
"message": "Git remote write failed",
"data": {
"name": "string",
"ref": "string"
}
}{
"defined": true,
"code": "EXTENSION_BUILD_UNAVAILABLE",
"status": 503,
"message": "Extension build service is unavailable",
"data": {
"name": "string"
}
}