Create a user agent
Create a new user agent from manifest and content. Creates an initial version automatically.
POST
/api/packages/agentsbetter-auth.session_token<token>
Cookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.
In: cookie
Header Parameters
X-Org-Id?string
Organization ID. Required for cookie auth. Not needed for API key auth (org resolved from key).
Format
uuidX-Space-Id?string
Space ID. Required for space-scoped routes (agents, runs, schedules, and space-scoped module routes). Not needed for API key auth (space resolved from key).
Request Body
application/json
curl -X POST "https://your-instance/api/packages/agents" \ -H "Content-Type: application/json" \ -d '{ "manifest": { "name": "string", "version": "string", "type": "agent", "display_name": "string", "author": "string", "schema_version": "string", "property1": null, "property2": null }, "content": "string" }'{
"id": "string",
"display_name": "string",
"description": "string",
"source": "local",
"scope": "string",
"version": "string",
"definition": "draft",
"manifest": {
"name": "string",
"version": "string",
"type": "agent",
"display_name": "string",
"description": "string",
"long_description": "string",
"keywords": [
"string"
],
"license": "string",
"author": "string",
"repository": "string",
"homepage": "string",
"documentation": "string",
"support": "string",
"icon": "string",
"icons": [
{
"src": "string",
"size": "string",
"theme": "light",
"property1": null,
"property2": null
}
],
"screenshots": [
"string"
],
"privacy_policies": [
"string"
],
"compatibility": {
"platforms": [
"darwin"
],
"runtimes": {
"property1": "string",
"property2": "string"
},
"clients": {
"property1": "string",
"property2": "string"
},
"property1": null,
"property2": null
},
"schema_version": "string",
"dependencies": {
"skills": {
"property1": "string",
"property2": "string"
},
"mcp_servers": {
"property1": "string",
"property2": "string"
},
"integrations": {
"property1": "string",
"property2": "string"
},
"property1": null,
"property2": null
},
"_meta": {
"property1": {
"property1": null,
"property2": null
},
"property2": {
"property1": null,
"property2": null
}
},
"integrations_configuration": {
"property1": {
"tools": [
"string"
],
"scopes": [
"string"
],
"auth_key": "string",
"property1": null,
"property2": null
},
"property2": {
"tools": [
"string"
],
"scopes": [
"string"
],
"auth_key": "string",
"property1": null,
"property2": null
}
},
"input": {
"schema": {
"definitions": {},
"dependencies": {},
"$recursiveAnchor": "string",
"$recursiveRef": "../dictionary",
"$id": "../dictionary",
"$schema": "http://example.com",
"$ref": "../dictionary",
"$anchor": "string",
"$dynamicRef": "../dictionary",
"$dynamicAnchor": "string",
"$vocabulary": {
"property1": true,
"property2": true
},
"$comment": "string",
"$defs": {
"property1": null,
"property2": null
},
"prefixItems": [
null
],
"items": null,
"contains": null,
"additionalProperties": null,
"properties": {},
"patternProperties": {},
"dependentSchemas": {},
"propertyNames": null,
"if": null,
"then": null,
"else": null,
"allOf": [
null
],
"anyOf": [
null
],
"oneOf": [
null
],
"not": null,
"unevaluatedItems": null,
"unevaluatedProperties": null,
"const": true,
"enum": [
true
],
"multipleOf": 1,
"maximum": 0,
"exclusiveMaximum": 0,
"minimum": 0,
"exclusiveMinimum": 0,
"maxLength": 0,
"minLength": 0,
"pattern": "/regex/",
"maxItems": 0,
"minItems": 0,
"uniqueItems": false,
"maxContains": 0,
"minContains": 1,
"maxProperties": 0,
"minProperties": 0,
"required": [],
"dependentRequired": {
"property1": [],
"property2": []
},
"title": "string",
"description": "string",
"default": true,
"deprecated": false,
"readOnly": false,
"writeOnly": false,
"examples": [
true
],
"format": "string",
"contentEncoding": "string",
"contentMediaType": "string",
"contentSchema": null,
"type": "object"
},
"file_constraints": {
"property1": {
"accept": "string",
"max_size": 1,
"property1": null,
"property2": null
},
"property2": {
"accept": "string",
"max_size": 1,
"property1": null,
"property2": null
}
},
"ui_hints": {
"property1": {
"placeholder": "string",
"property1": null,
"property2": null
},
"property2": {
"placeholder": "string",
"property1": null,
"property2": null
}
},
"property_order": [
"string"
],
"_meta": {
"property1": {
"property1": null,
"property2": null
},
"property2": {
"property1": null,
"property2": null
}
}
},
"output": {
"schema": {
"definitions": {},
"dependencies": {},
"$recursiveAnchor": "string",
"$recursiveRef": "../dictionary",
"$id": "../dictionary",
"$schema": "http://example.com",
"$ref": "../dictionary",
"$anchor": "string",
"$dynamicRef": "../dictionary",
"$dynamicAnchor": "string",
"$vocabulary": {
"property1": true,
"property2": true
},
"$comment": "string",
"$defs": {
"property1": null,
"property2": null
},
"prefixItems": [
null
],
"items": null,
"contains": null,
"additionalProperties": null,
"properties": {},
"patternProperties": {},
"dependentSchemas": {},
"propertyNames": null,
"if": null,
"then": null,
"else": null,
"allOf": [
null
],
"anyOf": [
null
],
"oneOf": [
null
],
"not": null,
"unevaluatedItems": null,
"unevaluatedProperties": null,
"const": true,
"enum": [
true
],
"multipleOf": 1,
"maximum": 0,
"exclusiveMaximum": 0,
"minimum": 0,
"exclusiveMinimum": 0,
"maxLength": 0,
"minLength": 0,
"pattern": "/regex/",
"maxItems": 0,
"minItems": 0,
"uniqueItems": false,
"maxContains": 0,
"minContains": 1,
"maxProperties": 0,
"minProperties": 0,
"required": [],
"dependentRequired": {
"property1": [],
"property2": []
},
"title": "string",
"description": "string",
"default": true,
"deprecated": false,
"readOnly": false,
"writeOnly": false,
"examples": [
true
],
"format": "string",
"contentEncoding": "string",
"contentMediaType": "string",
"contentSchema": null,
"type": "object"
},
"file_constraints": {
"property1": {
"accept": "string",
"max_size": 1,
"property1": null,
"property2": null
},
"property2": {
"accept": "string",
"max_size": 1,
"property1": null,
"property2": null
}
},
"ui_hints": {
"property1": {
"placeholder": "string",
"property1": null,
"property2": null
},
"property2": {
"placeholder": "string",
"property1": null,
"property2": null
}
},
"property_order": [
"string"
],
"_meta": {
"property1": {
"property1": null,
"property2": null
},
"property2": {
"property1": null,
"property2": null
}
}
},
"timeout": 1,
"property1": null,
"property2": null,
"runtime_tools": [
"output"
]
},
"prompt": "string",
"updatedAt": "2019-08-24T14:15:22Z",
"input": {
"values": {},
"locked_fields": [
"string"
],
"schema": {},
"file_constraints": {
"property1": {
"accept": "string",
"max_size": 0
},
"property2": {
"accept": "string",
"max_size": 0
}
},
"ui_hints": {
"property1": {
"placeholder": "string"
},
"property2": {
"placeholder": "string"
}
},
"property_order": [
"string"
]
},
"output": {
"schema": {},
"property_order": [
"string"
]
},
"dependencies": {
"skills": [
{
"id": "string",
"version": "string",
"name": "string",
"description": "string",
"home_writable": true
}
],
"mcp_servers": [
{
"id": "string",
"version": "string"
}
],
"integrations": [
{
"id": "string",
"version": "string",
"tools": [
"string"
],
"scopes": [
"string"
]
}
]
},
"last_run": {
"id": "string",
"status": "string",
"started_at": "2019-08-24T14:15:22Z",
"duration": 0
},
"running_runs": 0,
"version_count": 0,
"forked_from": "string",
"home_space_id": "string",
"home_writable": true,
"home_deletable": true,
"home_shareable": true,
"has_unarchived_changes": true,
"effective_timeout_seconds": 0,
"active": true
}{
"type": "https://docs.appstrate.dev/errors/validation-failed",
"title": "Validation Failed",
"status": 400,
"detail": "name: Invalid input: expected string, received undefined (+2 more)",
"code": "validation_failed",
"request_id": "req_abc123",
"errors": [
{
"field": "name",
"code": "required",
"message": "Invalid input: expected string, received undefined"
},
{
"field": "email",
"code": "invalid_format",
"message": "Invalid email address"
},
{
"field": "age",
"code": "invalid_type",
"message": "Invalid input: expected number, received string"
}
]
}{
"type": "https://docs.appstrate.dev/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Invalid or missing session",
"code": "unauthorized",
"request_id": "req_abc123"
}{
"type": "https://docs.appstrate.dev/errors/forbidden",
"title": "Forbidden",
"status": 403,
"detail": "Insufficient permissions",
"code": "forbidden",
"request_id": "req_abc123"
}{
"type": "https://docs.appstrate.dev/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Resource not found",
"code": "not_found",
"request_id": "req_abc123"
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"param": "string",
"retry_after": 0,
"errors": [
{
"field": "string",
"code": "string",
"message": "string",
"title": "string",
"candidate_connections": [
{
"id": "string",
"label": "string",
"account_id": "string",
"owned_by_actor": true,
"needs_reconnection": true
}
],
"connection_id": "string",
"missing_scopes": [
"string"
],
"owned_by_actor": true,
"required_scopes": [
"string"
],
"auth_key": "string",
"required_auth_key": "string",
"available_auth_keys": [
"string"
],
"connect_url": "http://example.com",
"expiresAt": "2019-08-24T14:15:22Z",
"packageId": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"param": "string",
"retry_after": 0,
"errors": [
{
"field": "string",
"code": "string",
"message": "string",
"title": "string",
"candidate_connections": [
{
"id": "string",
"label": "string",
"account_id": "string",
"owned_by_actor": true,
"needs_reconnection": true
}
],
"connection_id": "string",
"missing_scopes": [
"string"
],
"owned_by_actor": true,
"required_scopes": [
"string"
],
"auth_key": "string",
"required_auth_key": "string",
"available_auth_keys": [
"string"
],
"connect_url": "http://example.com",
"expiresAt": "2019-08-24T14:15:22Z",
"packageId": "string"
}
]
}