Skip to main content
POST
Deploy a new instance (catalog-driven via `variantId` or explicit).

Authorizations

Authorization
string
header
required

Pass a user JWT or a oag_ User API Key on the Authorization: Bearer <token> header. Both are validated by openapi-gateway against the Auth service.

Both credential types are user-scoped: every key (and every JWT) is bound to exactly one owner, and every route grants the caller full access to that owner's own resources. Cross-tenant access is denied by owner-ACL inside the handlers — there is no per-route scope vocabulary on this API.

Removed in v1.1.0: the legacy agents:* / tasks:* / files:* / instances:* scope set has been dropped together with the 403 insufficient_scope error. Existing oag_ keys automatically gain full owner-level access and do not need to be re-issued. SDK calls that previously passed scopes to createAPIKey should drop the argument. See the changelog at the bottom of this spec for the full migration note.

Body

application/json

Either supply a catalog variantId (authoritative — lifts agentFramework / providerId / region / scheduling hints from the variant) or provide an explicit agentFramework (+ optional providerId). Client-supplied scheduling fields (ownershipPreference / maxPricePerHour / resourceTypeHint) are not accepted here; the catalog variant is the source of truth.

name
string
required
Maximum string length: 128
variantId
string
Maximum string length: 128
agentFramework
string
Maximum string length: 64
providerId
string
Maximum string length: 64
providerConfig
object

Free-form provider-specific configuration merged with the catalog config (catalog wins on key conflicts).

modelPrimary
string
Maximum string length: 128
models
string[]
Maximum string length: 128
systemPrompt
string
Maximum string length: 8192
mcpServers
object
bridgeId
string
Maximum string length: 128
config
object

Alternate name for providerConfig; same semantics. Used by the variant-driven path to layer user extras (apiKeys / apiBaseUrls) on top of the catalog config.

clusterId
string
Maximum string length: 128
preferredRegion
string
Maximum string length: 64

Response

Standard envelope; data is the created instance.

success
boolean
required
data
object
required