---
title: Create support attachment upload
description: Reserve an image or screen recording upload owned by the caller.
  clientAttachmentId is a UUID; retry an unexpired pending reservation using
  identical metadata. Images may be at most 10 MiB and screen recordings 100
  MiB. fileName is a display name wit…
type: api-reference
source: ./openapi/inth-api.json
method: post
path: /v1/support/attachments
operationId: createSupportAttachmentUpload
server: https://api.inth.com
apiVersion: 1.0.0
tags:
  - Support
canonicalUrl: https://inth.com/docs/rest-api/support/create-support-attachment-upload
lastModified: "2026-10-30T15:16:34.514Z"
---
```http
POST /v1/support/attachments
```

Server: `https://api.inth.com`

Operation ID: `createSupportAttachmentUpload`

Reserve an image or screen recording upload owned by the caller. clientAttachmentId is a UUID; retry an unexpired pending reservation using identical metadata. Images may be at most 10 MiB and screen recordings 100 MiB. fileName is a display name without path separators or control characters. PUT the exact bytes to upload.url using upload.method and upload.mediaType as Content-Type. Do not forward the API bearer token to that signed storage URL. Then finalize the attachment before including its ID in a message. The upload URL expires at upload.expiresAt. Requires support.write and a user token. Organization API keys cannot call this operation. Uses customer permissions, with no operator or staff bypass. New mutations require rollout-agent-access-writes and allow-public-agent-writes to be enabled. Pausing writes leaves history and downloads available. Known IDs resolve their own organization; organizationId can require a specific tenant. Creation defaults to the saved organization.

## Authentication

* bearerAuth

### Schemes

* bearerAuth: http / bearer - Use an Inth API key or OAuth access token in the Authorization header.

  Product operations need a capability. Feedback intake only requires authentication. An OAuth access token carries the capabilities it was granted as scopes; an organization API key carries a fixed set (\`organizations.read\`, \`projects.read\`, \`projects.write\`, \`api-keys.read\`, \`inbox.read\`, \`billing.read\`), so writes that name the person who made them, such as \`inbox.write\` and \`vendors.write\`, need a user token. A credential without the capability an operation needs is answered with \`403 INSUFFICIENT\_SCOPE\`. \`GET /v1/me\` reports the capabilities of the calling credential.

  OAuth scopes:
  - \`organizations.read\`: List the organizations you belong to.
  - \`organizations.write\`: Create organizations you will own.
  - \`projects.read\`: Read projects, their consent configuration, and the vendors seen on them.
  - \`projects.write\`: Create, update, and delete projects and their consent configuration.
  - \`members.read\`: Read member names, email addresses, profile images, roles, and pending invitation email addresses.
  - \`members.write\`: Invite members, change member roles, remove members, and cancel invitations.
  - \`api-keys.read\`: List organization API keys.
  - \`api-keys.write\`: Create, roll, and delete organization API keys.
  - \`code-audit.read\`: Read Code Audit scans, their findings, and connected repositories.
  - \`code-audit.write\`: Start Code Audit scans and unlock their reports.
  - \`inbox.read\`: Read Inbox findings.
  - \`inbox.write\`: Change Inbox status or assignment and open GitHub issues for findings.
  - \`vendors.write\`: Approve or ignore vendors detected on your projects, which resolves their Inbox findings.
  - \`billing.read\`: Read the plan and credit balance of an organization.
  - \`billing.details.read\`: Read invoices, billing profiles, and payment method summaries for organizations you own.
  - \`consent.read\`: Read consent records, analytics, configuration, and runtime status.
  - \`consent.write\`: Update consent settings, translations, IAB configuration, and policies.
  - \`consent.keys.read\`: Read consent runtime key metadata. Secret values are never returned.
  - \`website-audit.read\`: Read website audit targets, scans, reports, cookies, and evidence.
  - \`website-audit.write\`: Manage website audit targets, verify domains, review findings, and start scans.
  - \`account.read\`: Read your account profile.
  - \`notifications.read\`: Read your notification preferences and organization routing.
  - \`organization-retention.read\`: Read organization provider data retention policy.
  - \`support.read\`: Read support conversations you own or can access through sharing.
  - \`support.write\`: Create support conversations, send messages, share or close them, and upload support attachments.
  - \`consent.lifecycle.write\`: Update, upgrade or delete Consent runtimes.
  - \`consent.keys.write\`: Create, rotate and revoke Consent runtime keys.
  - \`billing.write\`: Preview and change plans, buy credits, manage billing details and subscriptions, and open hosted payment flows.
  - \`account.security.read\`: Read your active browser sessions and connected device grants.
  - \`account.security.write\`: Revoke your browser sessions and connected device grants.
  - \`integrations.read\`: Read connected integration accounts, repositories, provider properties and project links.
  - \`integrations.write\`: Connect and sync providers, manage repository settings, project links and paid pull request monitoring.
  - \`account.write\`: Update your name, avatar and PII masking preference.
  - \`account.delete\`: Permanently delete your account after ownership checks and confirmation.
  - \`notifications.write\`: Update your notification preferences.
  - \`notifications.routing.write\`: Manage organization notification routing.
  - \`organization-retention.write\`: Change organization provider data retention policy.
  - \`organizations.settings.write\`: Update organization name, logo and slug.
  - \`organizations.delete\`: Permanently delete organizations you own after confirmation.
  - \`agents.read\`: Read your Inth Agent chats and chats shared with your organization.
  - \`agents.write\`: Start Inth Agent chats, send messages, share your chats with the organization, and delete your chats. Agent replies use organization credits.

## Request

### Query Parameters

|Name|Type|Required|Description|
|:--|:--|:--|:--|
|`organizationId`|string|optional|For lists, omit to use the saved organization. A known conversation resolves its organization independently; pass this to require a specific organization.|

### Request Body

required

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`clientAttachmentId`|string (uuid)|required||
|`fileName`|string|required||
|`mediaType`|"image/gif" \|"image/jpeg" \|"image/png" \|"image/webp" \|"video/mp4" \|"video/quicktime" \|"video/webm"|required||
|`sizeBytes`|integer|required||

JSON Schema:

```json
{
  "type": "object",
  "properties": {
    "clientAttachmentId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid"
    },
    "fileName": {
      "type": "string"
    },
    "mediaType": {
      "type": "string",
      "enum": [
        "image/gif",
        "image/jpeg",
        "image/png",
        "image/webp",
        "video/mp4",
        "video/quicktime",
        "video/webm"
      ]
    },
    "sizeBytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    }
  },
  "required": [
    "clientAttachmentId",
    "fileName",
    "mediaType",
    "sizeBytes"
  ],
  "additionalProperties": false
}
```

## Code Examples

### cURL

```bash
curl -X POST "https://api.inth.com/v1/support/attachments" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "clientAttachmentId": "123e4567-e89b-12d3-a456-426614174000",
  "fileName": "string",
  "mediaType": "image/gif",
  "sizeBytes": 0
}'
```

### JavaScript

```ts
const response = await fetch("https://api.inth.com/v1/support/attachments", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "clientAttachmentId": "123e4567-e89b-12d3-a456-426614174000",
    "fileName": "string",
    "mediaType": "image/gif",
    "sizeBytes": 0
  }),
});
const data = await response.json();
```

## Responses

### 201

Success

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|unknown|required||
|`data`|object|required||
|`data.attachment`|object|required||
|`data.attachment.id`|string|required||
|`data.attachment.messageId`|string \|null|required||
|`data.attachment.fileName`|string|required||
|`data.attachment.mediaType`|string|required||
|`data.attachment.sizeBytes`|integer|required||
|`data.attachment.kind`|"image" \|"screen\_recording" \|"file"|required||
|`data.attachment.status`|"uploading" \|"ready" \|"failed"|required||
|`data.attachment.downloadUrl`|string|required||
|`data.attachment.failureReason`|string \|null|optional||
|`data.attachment.createdAt`|string|required|An ISO 8601 UTC date-time string.|
|`data.attachment.uploadedAt`|string \|null|required||
|`data.upload`|object|required||
|`data.upload.method`|"PUT"|required||
|`data.upload.url`|string|required||
|`data.upload.mediaType`|"image/gif" \|"image/jpeg" \|"image/png" \|"image/webp" \|"video/mp4" \|"video/quicktime" \|"video/webm" \|"application/pdf" \|"application/octet-stream"|required||
|`data.upload.expiresAt`|string|required|An ISO 8601 UTC date-time string.|

Example:

```json
{
  "success": {},
  "data": {
    "attachment": {
      "id": "string",
      "messageId": "string",
      "fileName": "string",
      "mediaType": "string",
      "sizeBytes": 0,
      "kind": "image",
      "status": "uploading",
      "downloadUrl": "string",
      "failureReason": "string",
      "createdAt": "string",
      "uploadedAt": "string"
    },
    "upload": {
      "method": "PUT",
      "url": "string",
      "mediaType": "image/gif",
      "expiresAt": "string"
    }
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "data"
  ],
  "properties": {
    "success": {
      "const": true
    },
    "data": {
      "type": "object",
      "properties": {
        "attachment": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "maxLength": 64,
              "pattern": "^sat_[1-9a-km-z]+$"
            },
            "messageId": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 64,
                  "pattern": "^spm_[1-9a-km-z]+$"
                },
                {
                  "type": "null"
                }
              ]
            },
            "fileName": {
              "type": "string"
            },
            "mediaType": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64
            },
            "sizeBytes": {
              "type": "integer",
              "minimum": 0,
              "maximum": 4294967295
            },
            "kind": {
              "type": "string",
              "enum": [
                "image",
                "screen_recording",
                "file"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "uploading",
                "ready",
                "failed"
              ]
            },
            "downloadUrl": {
              "type": "string",
              "pattern": "^\\/v1\\/support\\/attachments\\/sat_[1-9a-km-z]+\\/content$"
            },
            "failureReason": {
              "anyOf": [
                {
                  "type": "string",
                  "maxLength": 1000
                },
                {
                  "type": "null"
                }
              ]
            },
            "createdAt": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$",
              "title": "Support date-time",
              "description": "An ISO 8601 UTC date-time string."
            },
            "uploadedAt": {
              "anyOf": [
                {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$",
                  "title": "Support date-time",
                  "description": "An ISO 8601 UTC date-time string."
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "messageId",
            "fileName",
            "mediaType",
            "sizeBytes",
            "kind",
            "status",
            "downloadUrl",
            "createdAt",
            "uploadedAt"
          ],
          "additionalProperties": false
        },
        "upload": {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "PUT"
              ]
            },
            "url": {
              "type": "string",
              "maxLength": 2048,
              "pattern": "^https:\\/\\/[^\\s]+$"
            },
            "mediaType": {
              "type": "string",
              "enum": [
                "image/gif",
                "image/jpeg",
                "image/png",
                "image/webp",
                "video/mp4",
                "video/quicktime",
                "video/webm",
                "application/pdf",
                "application/octet-stream"
              ]
            },
            "expiresAt": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,9})?Z$",
              "title": "Support date-time",
              "description": "An ISO 8601 UTC date-time string."
            }
          },
          "required": [
            "method",
            "url",
            "mediaType",
            "expiresAt"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "attachment",
        "upload"
      ],
      "additionalProperties": false
    }
  }
}
```

### 400

The request payload or parameters are invalid.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSUFFICIENT\_SCOPE" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"INSUFFICIENT\_CREDITS" \|"SCAN\_IN\_PROGRESS" \|"UNLOCK\_REQUIRED" \|"REPOSITORY\_NOT\_LINKED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example: default

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PAYLOAD",
    "message": "Invalid request payload",
    "details": [
      {
        "code": "too_small",
        "message": "Too small: expected string to have >=1 characters",
        "path": [
          "name"
        ]
      }
    ]
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSUFFICIENT_SCOPE",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "INSUFFICIENT_CREDITS",
            "SCAN_IN_PROGRESS",
            "UNLOCK_REQUIRED",
            "REPOSITORY_NOT_LINKED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 401

Authentication is missing, invalid, or expired.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSUFFICIENT\_SCOPE" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"INSUFFICIENT\_CREDITS" \|"SCAN\_IN\_PROGRESS" \|"UNLOCK\_REQUIRED" \|"REPOSITORY\_NOT\_LINKED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example: default

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSUFFICIENT_SCOPE",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "INSUFFICIENT_CREDITS",
            "SCAN_IN_PROGRESS",
            "UNLOCK_REQUIRED",
            "REPOSITORY_NOT_LINKED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 403

The credential is valid but may not perform the operation.

\`INSUFFICIENT\_SCOPE\`: the credential was never granted the capability the operation needs. \`details.requiredScope\` names it, and the \`WWW-Authenticate\` header carries \`Bearer error="insufficient\_scope"\`. An OAuth client fixes this by requesting the scope; an organization API key cannot gain it.

\`FORBIDDEN\`: the capability is present but the membership behind the credential lacks the role, or the resource belongs to another organization.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSUFFICIENT\_SCOPE" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"INSUFFICIENT\_CREDITS" \|"SCAN\_IN\_PROGRESS" \|"UNLOCK\_REQUIRED" \|"REPOSITORY\_NOT\_LINKED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example: insufficientScope

```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This token was not granted the projects.write scope",
    "details": {
      "requiredScope": "projects.write"
    }
  }
}
```

Example: forbidden

```json
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Organization membership is required"
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSUFFICIENT_SCOPE",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "INSUFFICIENT_CREDITS",
            "SCAN_IN_PROGRESS",
            "UNLOCK_REQUIRED",
            "REPOSITORY_NOT_LINKED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

#### Headers

|Name|Type|Required|Description|
|:--|:--|:--|:--|
|`WWW-Authenticate`|string|optional|Present on \`INSUFFICIENT\_SCOPE\`: \`Bearer error="insufficient\_scope", scope="\<required scope>"\`.|

### 404

The requested resource was not found.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSUFFICIENT\_SCOPE" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"INSUFFICIENT\_CREDITS" \|"SCAN\_IN\_PROGRESS" \|"UNLOCK\_REQUIRED" \|"REPOSITORY\_NOT\_LINKED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example:

```json
{
  "success": true,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "string",
    "details": {}
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSUFFICIENT_SCOPE",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "INSUFFICIENT_CREDITS",
            "SCAN_IN_PROGRESS",
            "UNLOCK_REQUIRED",
            "REPOSITORY_NOT_LINKED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 409

The request conflicts with the current resource state.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSUFFICIENT\_SCOPE" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"INSUFFICIENT\_CREDITS" \|"SCAN\_IN\_PROGRESS" \|"UNLOCK\_REQUIRED" \|"REPOSITORY\_NOT\_LINKED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example:

```json
{
  "success": true,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "string",
    "details": {}
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSUFFICIENT_SCOPE",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "INSUFFICIENT_CREDITS",
            "SCAN_IN_PROGRESS",
            "UNLOCK_REQUIRED",
            "REPOSITORY_NOT_LINKED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 503

Public agent writes are paused by allow-public-agent-writes. Retry after operators resume writes.

## Related

* [REST API overview](/docs/rest-api): Every operation in this API.