> ## Documentation Index > Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt > Use this file to discover all available pages before exploring further. # Pre-upload a file > Create an Attachment upload allocation. ## OpenAPI ````yaml /api-reference/openapi.mint.yaml post /v1/attachments openapi: 3.1.0 info: title: Relay API version: 1.0.0 description: >- Create conversations between users and agents. Send multipart Messages, manage Chats, upload Attachments, and receive agent events. license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.relayapp.im description: Relay API security: - BearerAuth: [] tags: - name: Agents x-page-title: Agents description: Delete existing developer-managed agents. - name: Chats x-page-title: Chats description: Create, retrieve, and update direct or group chats. - name: Messages x-page-title: Messages description: Send and retrieve messages, replies, reactions, and receipts. - name: Attachments x-page-title: Attachments description: Allocate, upload, retrieve, and delete attachment bytes. - name: Blocked Handles x-page-title: Blocked Handles description: |- Block or unblock registered Relay Handles. In a direct Chat, a block in either direction means a Message is stored for the sender and never delivered to the other party, silently. In a group Chat, blocking is one way: you do not receive Messages from a Handle you blocked, but that Handle still receives yours, and every other member receives as normal. Blocking does not delete existing Chats or history. - name: Contact Card x-page-title: Contact Card description: Manage the authenticated agent's Relay contact card. - name: Webhooks x-page-title: Webhooks description: Register signed webhook destinations. - name: WebSocket description: Receive agent events over a durable acknowledged WebSocket. - name: Contacts description: Request a user Contact. paths: /v1/attachments: post: tags: - Attachments summary: Pre-upload a file description: Create an Attachment upload allocation. operationId: requestUpload requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RequestUploadRequest' responses: '200': description: Upload URL generated successfully content: application/json: schema: $ref: '#/components/schemas/RequestUploadResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '413': description: '`size_bytes` is over 100 MiB (104857600 bytes).' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: The request Content-Type is not `application/json`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: schemas: RequestUploadRequest: type: object required: - filename - content_type - size_bytes properties: filename: type: string description: Name of the file to upload minLength: 1 maxLength: 255 content_type: type: string maxLength: 255 pattern: ^[A-Za-z0-9!#$%&'*+.^_`|~-]+/[A-Za-z0-9!#$%&'*+.^_`|~-]+$ description: >- MIME type of the file, as `type/subtype`. Relay accepts any file type and stores the bytes unchanged; the declared type is lowercased and returned to the reader as sent. size_bytes: type: integer format: int64 description: Size of the file in bytes (max 100MB) minimum: 1 maximum: 104857600 duration_ms: type: - integer - 'null' minimum: 0 description: >- Audio or video duration in milliseconds when known. Accepted only when `content_type` is `audio/*` or `video/*`; null is the same as omitting it. width: type: - integer - 'null' minimum: 1 description: >- Pixel width when known. Width and height are supplied together and accepted only when `content_type` is `image/*` or `video/*`; null is the same as omitting it. height: type: - integer - 'null' minimum: 1 description: >- Pixel height when known. Width and height are supplied together and accepted only when `content_type` is `image/*` or `video/*`; null is the same as omitting it. RequestUploadResult: type: object required: - attachment_id - upload_url - download_url - http_method - expires_at - required_headers properties: attachment_id: type: string description: Unique identifier for the attachment format: uuid upload_url: type: string format: uri description: >- Opaque Relay upload URL. PUT the raw bytes with the exact required_headers before expires_at. download_url: type: string format: uri description: Opaque Relay download URL for the Attachment. http_method: type: string description: HTTP method to use for upload (always PUT) enum: - PUT expires_at: type: string format: date-time description: When the upload URL expires (15 minutes from now) required_headers: type: object description: Exact HTTP headers required by the upload URL. additionalProperties: type: string ErrorResponse: type: object required: - error - success properties: error: $ref: '#/components/schemas/ErrorDetail' success: type: boolean description: Always false for error responses trace_id: type: string description: Unique trace ID for request tracing and debugging ErrorDetail: type: object required: - status - code - message - doc_url properties: status: type: integer description: HTTP status code (e.g., 400, 404, 500) code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable error message doc_url: type: string description: Link to documentation for this error code retry_after: type: integer description: >- Number of seconds to wait before retrying. Only present on 429 rate limit errors. ErrorCode: type: integer description: Relay API error code. responses: BadRequest: description: Invalid request - validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Unauthorized - missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer description: > Bearer token authentication. Include your API token in the Authorization header. Format: `Authorization: Bearer ` ````