> ## Documentation Index > Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually. > The skills index at https://github.com/getcargohq/cargo-skills/blob/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles. > Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up. > Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate. # Update role > Update a custom role's permissions ## OpenAPI ````yaml https://api.getcargo.io/openapi.json patch /workspaceManagement/roles/{uuid} openapi: 3.1.0 info: title: Cargo API version: 1.0.0 description: |- Cargo Platform API v1. ## Authentication Every endpoint requires a bearer token: `Authorization: Bearer `. There is no unauthenticated endpoint. Create a token with `cargo-ai login`. ## Errors Every 4xx and 5xx response is a JSON object carrying `errorMessage`, a human-readable description of what went wrong. A long tail of orchestration routes carries `reason` instead, a machine-readable cause. Routes may add fields, so treat the object as open rather than closed. ## Rate limits Requests are counted per workspace. A limited response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy`, and the legacy `X-RateLimit-*` spellings alongside them. A 429 carries `Retry-After` in seconds: back off by that, rather than retrying immediately. ## Versioning and deprecation The version is in the path (`/v1`), and a breaking change ships as a new path rather than by altering this one. Adding a field to a response, a new optional request field, or a new endpoint is not breaking, so a client must ignore fields it does not recognise. When an endpoint is being retired it carries the `Deprecation` header (RFC 9745) and, once a removal date is fixed, `Sunset` (RFC 8594). Both are HTTP dates. An endpoint marked `deprecated` in this document is still served until its `Sunset` passes. servers: - url: https://api.getcargo.io/v1 description: Cargo API security: - bearerAuth: [] paths: /workspaceManagement/roles/{uuid}: patch: tags: - Workspace Management - Roles summary: Update role description: Update a custom role's permissions operationId: patchWorkspaceManagementRolesByUuid parameters: - in: path name: uuid schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$ title: UUID description: Role identifier. required: true description: Role identifier. requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 255 title: Name description: Display name for the role. color: type: string enum: - orange - red - purple - green - yellow - grey title: Color description: Color shown as a dot next to the role name. description: anyOf: - type: string minLength: 1 maxLength: 1000 title: Description description: Optional description shown next to the role name. - type: 'null' permissions: type: array items: type: object properties: effect: type: string enum: - allow - deny resources: anyOf: - type: array items: type: string - type: 'null' actions: type: array items: type: string enum: - ai:* - ai:read - ai:write - ai:agent:* - ai:agent:read - ai:agent:write - ai:mcpServer:* - ai:mcpServer:read - ai:mcpServer:write - billing:* - billing:read - billing:write - connection:* - connection:read - connection:write - context:* - context:read - context:write - domainManagement:* - domainManagement:read - domainManagement:write - hosting:* - hosting:read - hosting:write - hosting:app:* - hosting:app:read - hosting:app:write - hosting:worker:* - hosting:worker:read - hosting:worker:write - mailboxManagement:* - mailboxManagement:read - mailboxManagement:write - observability:* - observability:read - observability:write - orchestration:* - orchestration:read - orchestration:write - orchestration:workflow:* - orchestration:workflow:read - orchestration:workflow:write - revenueOrganization:* - revenueOrganization:read - revenueOrganization:write - segmentation:* - segmentation:read - segmentation:write - storage:* - storage:read - storage:write - content:* - content:read - content:write - content:file:* - content:file:read - content:file:write - systemOfRecordIntegration:* - systemOfRecordIntegration:read - systemOfRecordIntegration:write - workspaceManagement:* - workspaceManagement:read - workspaceManagement:write - workspaceManagement:folder:* - workspaceManagement:folder:read - workspaceManagement:folder:write required: - effect - resources - actions title: Permissions description: Permission grants for the role. additionalProperties: false title: Request body description: Request body schema. responses: '200': description: Successful response content: application/json: schema: type: object properties: role: type: object properties: uuid: type: string name: type: string slug: type: string color: type: string enum: - orange - red - purple - green - yellow - grey description: anyOf: - type: string - type: 'null' permissions: type: array items: type: object properties: effect: type: string enum: - allow - deny resources: anyOf: - type: array items: type: string - type: 'null' actions: type: array items: type: string enum: - ai:* - ai:read - ai:write - ai:agent:* - ai:agent:read - ai:agent:write - ai:mcpServer:* - ai:mcpServer:read - ai:mcpServer:write - billing:* - billing:read - billing:write - connection:* - connection:read - connection:write - context:* - context:read - context:write - domainManagement:* - domainManagement:read - domainManagement:write - hosting:* - hosting:read - hosting:write - hosting:app:* - hosting:app:read - hosting:app:write - hosting:worker:* - hosting:worker:read - hosting:worker:write - mailboxManagement:* - mailboxManagement:read - mailboxManagement:write - observability:* - observability:read - observability:write - orchestration:* - orchestration:read - orchestration:write - orchestration:workflow:* - orchestration:workflow:read - orchestration:workflow:write - revenueOrganization:* - revenueOrganization:read - revenueOrganization:write - segmentation:* - segmentation:read - segmentation:write - storage:* - storage:read - storage:write - content:* - content:read - content:write - content:file:* - content:file:read - content:file:write - systemOfRecordIntegration:* - systemOfRecordIntegration:read - systemOfRecordIntegration:write - workspaceManagement:* - workspaceManagement:read - workspaceManagement:write - workspaceManagement:folder:* - workspaceManagement:folder:read - workspaceManagement:folder:write required: - effect - resources - actions additionalProperties: false workspaceUuid: type: string createdAt: type: string updatedAt: type: string deletedAt: anyOf: - type: string - type: 'null' required: - uuid - name - slug - color - description - permissions - workspaceUuid - createdAt - updatedAt - deletedAt additionalProperties: false required: - role additionalProperties: false '400': description: Bad request content: application/json: schema: type: object properties: errorMessage: description: Human-readable description of what went wrong. type: string reason: description: >- Machine-readable cause, used where a route distinguishes failure modes. type: string additionalProperties: false description: Error response '401': description: Unauthorized content: application/json: schema: type: object properties: errorMessage: description: Human-readable description of what went wrong. type: string reason: description: >- Machine-readable cause, used where a route distinguishes failure modes. type: string additionalProperties: false description: Error response '404': description: Not found content: application/json: schema: type: object properties: errorMessage: description: Human-readable description of what went wrong. type: string reason: description: >- Machine-readable cause, used where a route distinguishes failure modes. type: string additionalProperties: false description: Error response '429': description: >- Too many requests. Retry after the number of seconds in the Retry-After header. content: application/json: schema: type: object properties: errorMessage: description: Human-readable description of what went wrong. type: string reason: description: >- Machine-readable cause, used where a route distinguishes failure modes. type: string additionalProperties: false description: Error response '500': description: Internal server error content: application/json: schema: type: object properties: errorMessage: description: Human-readable description of what went wrong. type: string reason: description: >- Machine-readable cause, used where a route distinguishes failure modes. type: string additionalProperties: false description: Error response components: securitySchemes: bearerAuth: type: http scheme: bearer ````