Update a user agent

Update manifest and content of a user agent, under its If-Match. Authority is the package's HOME space (packages.home_space_id, RBAC spec §6.9): this route requires the package type's write (delete for a delete) THERE and nowhere else — not in the space the request is made from, which merely consumes a placement and has no say over the draft, the versions or the identity. Every package of the organization has a home; one that belongs to no team is homed in the organization's default space, which owners and admins reach like any other. An id the caller cannot READ at all answers 404 rather than 403, so this is not an existence oracle. Move the home with PUT /api/packages/{scope}/{name}/home.

PATCH/api/packages/agents/{scope}/{name}

Authorization

better-auth.session_token<token>

Cookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.

In: cookie

Path Parameters

scope*string

Package scope (e.g. @myorg)

Match^@[a-z0-9][a-z0-9-]*$

name*string

Package name

Header Parameters

X-Org-Id?string

Organization ID. Required for cookie auth. Not needed for API key auth (org resolved from key).

Formatuuid

X-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).

If-Match*string

The ETag of the draft the write is based on (read it from the package GET, or from the previous write's response). Mandatory: absent is 428 precondition_required; stale is 412 precondition_failed and nothing is written. * writes over whatever is current.

Request Body

application/json

manifest?

AFPS Agent manifest extended with Appstrate platform fields. Standard fields are defined by the AFPS Agent schema. Most extension fields use the x- prefix per AFPS §10, with the exception of the Appstrate-specific top-level runtime_tools field documented below.

content?string

operations?array<||>

Ordered file edits saved with the manifest. On creation they are validated before creating the package and included in its initial version. Updates are guarded by the same If-Match as the manifest; a stale draft returns 412 without applying the batch. manifest.json is edited through manifest; required content cannot be deleted or moved. Executable file edits validate bundle references. There is no cap on the number of operations, so a whole working folder can be written in one atomic request: the bounds are bytes — the global request body limit (API_BODY_LIMIT_BYTES), 1 MiB per written file (413 file_too_large), and 50 MB / 10,000 entries for the resulting tree (413 tree_too_large). Legacy content, when supplied, is applied before operations.

Items1 <= items

curl -X PATCH "https://your-instance/api/packages/agents/string/string" \  -H "If-Match: "42"" \  -H "Content-Type: application/json" \  -d '{}'

{
  "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": "https://docs.appstrate.dev/errors/precondition-failed",
  "title": "Precondition Failed",
  "status": 412,
  "detail": "The resource changed since you read it: If-Match does not match its current ETag. Re-read it, reapply your change, and send the new ETag.",
  "code": "precondition_failed",
  "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": "https://docs.appstrate.dev/errors/precondition-required",
  "title": "Precondition Required",
  "status": 428,
  "detail": "This write requires an If-Match header carrying the ETag of the representation you read. GET the resource, then send its ETag.",
  "code": "precondition_required",
  "request_id": "req_abc123"
}

Update a user agent

Authorization

Path Parameters

Header Parameters

Request Body

Multiple body fields failed validation

Single non-body field failed validation