> ## Documentation Index > Fetch the complete documentation index at: https://docs.matrices.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a private image upload > Creates a short-lived grant for one direct object-store PUT. The PUT body must contain exactly image.size bytes and send every returned header unchanged; browser File and Blob bodies derive the signed Content-Length automatically. The URL is a bearer and must not be logged, persisted, or shared. A grant succeeds once because the object is created with If-None-Match "*". Retry by creating a new upload, which may store duplicate bytes under another image ID. Upload success means private bytes were stored, not that a model decoded them; malformed or mislabeled bytes may be rejected by a later model request. ## OpenAPI ````yaml /openapi/platform.v1.json post /v1/agents/{agentId}/images openapi: 3.0.3 info: description: Public platform API for catalog and proxied data-plane routes. title: Matrices Platform API version: v1 servers: - url: https://api.matrices.com security: [] tags: - description: Authenticated bearer credential context. name: auth x-group: Auth - description: Write-only provider credentials with safe connection metadata. name: connections x-group: Connections - description: Materialized workspace principals and active agent counts. name: identities x-group: Identities - description: Remote MCP server registrations. name: toolsets x-group: Toolsets - description: Named allow-only agent tool permissions. name: roles x-group: Roles - description: Client-executed tool calls. name: tools x-group: Tools - description: Reusable agent behavior profiles. name: profiles x-group: Profiles - description: Workspace-owned agent identities. name: agents x-group: Agents - description: Immutable private image inputs. name: images x-group: Images - description: Public model catalog. name: models x-group: Models - description: Running agent threads. name: threads x-group: Threads - description: Agent schedules. name: schedules x-group: Schedules - description: Workspace append-only feeds. name: feeds x-group: Feeds - description: Agent subscriptions over workspace feeds. name: subscriptions x-group: Subscriptions - description: Agent-private and workspace-shared durable memory notes. name: memory x-group: Memory - description: Thread messages. name: messages x-group: Messages - description: Thread event log data. name: events x-group: Events - description: Runtime hook audit and wait resolution. name: hooks x-group: Hooks paths: /v1/agents/{agentId}/images: post: tags: - images summary: Create a private image upload description: >- Creates a short-lived grant for one direct object-store PUT. The PUT body must contain exactly image.size bytes and send every returned header unchanged; browser File and Blob bodies derive the signed Content-Length automatically. The URL is a bearer and must not be logged, persisted, or shared. A grant succeeds once because the object is created with If-None-Match "*". Retry by creating a new upload, which may store duplicate bytes under another image ID. Upload success means private bytes were stored, not that a model decoded them; malformed or mislabeled bytes may be rejected by a later model request. operationId: CreateImageUpload parameters: - $ref: '#/components/parameters/AgentID' requestBody: content: application/json: schema: $ref: '#/components/schemas/ImageUploadRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ImageUploadResponse' description: Direct upload grant created. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/PayloadTooLarge' '502': $ref: '#/components/responses/RuntimeUpstreamError' '503': $ref: '#/components/responses/RuntimeUnavailable' security: - APIKeyBearer: [] components: parameters: AgentID: in: path name: agentId required: true schema: type: string schemas: ImageUploadRequest: additionalProperties: false properties: format: $ref: '#/components/schemas/ImageFormat' size: format: int64 maximum: 3750000 minimum: 1 type: integer required: - format - size type: object ImageUploadResponse: additionalProperties: false properties: image: $ref: '#/components/schemas/Image' upload: $ref: '#/components/schemas/ImageUploadGrant' required: - image - upload type: object ImageFormat: description: Caller-declared encoded image format. enum: - jpeg - png - gif - webp type: string Image: additionalProperties: false properties: format: $ref: '#/components/schemas/ImageFormat' id: $ref: '#/components/schemas/ImageID' size: format: int64 maximum: 3750000 minimum: 1 type: integer required: - id - format - size type: object ImageUploadGrant: additionalProperties: false properties: expiresAt: format: date-time type: string headers: $ref: '#/components/schemas/ImageUploadHeaders' url: description: Short-lived upload bearer. Do not log, persist, or share it. format: uri type: string required: - url - headers - expiresAt type: object ErrorResponse: properties: attemptsRemaining: type: integer code: type: string error: type: string message: type: string retryAfterSeconds: type: integer required: - error - message type: object ImageID: description: Opaque identifier for one immutable private image. maxLength: 68 minLength: 68 pattern: ^img_[0-9a-f]{64}$ type: string ImageUploadHeaders: additionalProperties: false properties: content-type: enum: - image/jpeg - image/png - image/gif - image/webp type: string if-none-match: enum: - '*' type: string required: - content-type - if-none-match type: object responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid request. NotFound: content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Resource not found. PayloadTooLarge: content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Request payload is too large. RuntimeUpstreamError: content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Runtime environment returned an upstream error. RuntimeUnavailable: content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Runtime environment is unavailable or cannot be selected. securitySchemes: APIKeyBearer: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.