> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add an Attachment

> Upload a file attachment to a specific record

## Overview

Upload file attachments to records in Elementum. Files are stored as attachments on the record and accessible through the record's attachments block.

<Warning>
  **File Size Limit**: Maximum file size is **250MB** per attachment.
</Warning>

## Endpoint

```
POST https://api.elementum.io/v1/elements/{elementname}/{record-handle}/attachments
```

## Request

The request body should be `multipart/form-data` containing the file to upload.

**Path Parameters:**

* `elementname` - The namespace of your element (e.g., `testelement`)
* `record-handle` - The unique identifier for the record (e.g., `TTE-11`)

**Headers:**

* `Authorization: Bearer {access_token}`
* `Content-Type: multipart/form-data`

**Body:**

* `file` (required) - The file to upload
* `description` (optional) - Description for the attachment

## Example Request

```bash theme={null}
curl -X POST 'https://api.elementum.io/v1/elements/testelement/TTE-11/attachments' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -F 'file=@/path/to/document.pdf' \
  -F 'description=Contract document'
```

## Response

**Success (202 Accepted):**

```json theme={null}
{
  "id": "att_abc123xyz",
  "name": "document.pdf",
  "description": "Contract document",
  "mediaType": "application/pdf",
  "size": 2458624,
  "state": "processing",
  "createdAt": "2025-01-08T14:30:00Z"
}
```

<Info>
  The `202 Accepted` status indicates the file upload has been accepted and is being processed asynchronously.
</Info>

**Common Errors:**

* `400` - Invalid file or exceeds size limit
* `401` - Invalid or expired access token
* `404` - Record not found
* `413` - File exceeds 250MB size limit

## Related Documentation

<CardGroup cols={2}>
  <Card title="File Uploads Guide" icon="book" href="/workflows/file-uploads-attachments">
    Comprehensive guide to working with files and attachments
  </Card>

  <Card title="Add a Link" icon="link" href="/api-reference/endpoints/attachments/add-a-link">
    Add a URL link as an attachment
  </Card>

  <Card title="Delete Attachment" icon="trash" href="/api-reference/endpoints/attachments/delete-a-record-attachment">
    Remove an attachment from a record
  </Card>

  <Card title="API Introduction" icon="code" href="/api-reference/api-introduction">
    Authentication and getting started
  </Card>
</CardGroup>


## OpenAPI

````yaml post /{recordType}/{alias}/{id}/attachments
openapi: 3.0.1
info:
  title: Elementum API
  description: ''
  contact:
    email: apiteam@elementum.io
  version: 0.0.1
servers:
  - url: /v1
security: []
tags:
  - name: Access Token
    description: Manage access tokens using OAuth 2.0 standards
  - name: Records
    description: Manage your records
  - name: Related-items
    description: Manage the related items of a record
  - name: Attachments
    description: Manage the attachments of a record
  - name: Watchers
    description: Manage the watchers of a record
  - name: Comments
    description: Manage the conversation of a record
  - name: Users
    description: Manage users in your organization
  - name: Groups
    description: Manage groups and group membership
externalDocs:
  description: Find out more about Elementum
  url: https://www.elementum.com/
paths:
  /{recordType}/{alias}/{id}/attachments:
    post:
      tags:
        - Attachments
      summary: Add an attachment
      operationId: createRecordAttachment
      parameters:
        - $ref: '#/components/parameters/recordType'
        - $ref: '#/components/parameters/alias'
        - $ref: '#/components/parameters/recordId'
      requestBody:
        description: the attachment to be uploaded
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/File'
        required: true
      responses:
        '202':
          description: Accepted
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      security:
        - ClientCredentials: []
components:
  parameters:
    recordType:
      name: recordType
      in: path
      description: '''apps'', ''elements'', ''tasks'', or ''transactions'''
      required: true
      schema:
        type: string
        format: string
    alias:
      name: alias
      in: path
      description: The application alias
      required: true
      schema:
        type: string
        format: string
    recordId:
      name: id
      in: path
      description: The record ID
      required: true
      schema:
        type: string
        format: string
  schemas:
    File:
      type: object
      properties:
        file:
          type: string
          format: binary
  responses:
    '400':
      description: Bad Request
    '401':
      description: Unauthorized
    '403':
      description: Forbidden
    '404':
      description: Not Found
    '422':
      description: Unprocessable Entity
    '429':
      description: Too Many Requests
    '500':
      description: Internal Server Error
  securitySchemes:
    ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}

````