> ## Documentation Index > Fetch the complete documentation index at: https://formhug.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Prepare an entry-attachment upload > Prepare an upload for an `attachment` field. Returns a one-time `upload_id` and an `upload_url`. Send the file to `upload_url` with an HTTP `PUT`: the raw file bytes as the request body and the `Content-Type` header set to the value you declared in `content_type` (it must match). Use the `upload_url` exactly as returned. Then submit the returned `upload_id` under the attachment field in `field_values` when creating the entry — the entry-create endpoint registers the attachment. No PAT scope required. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/v1/f/{form_token}/entry_attachments openapi: 3.0.1 info: title: FormHug API V1 version: v1 description: | FormHug public REST API. All request/response keys are snake_case. Successful response: ```json { "data": { ... } } ``` Paginated response: ```json { "data": [ ... ], "pagination": { "total": 123, "next_cursor": "NQ==" } } ``` Error response: ```json { "error": "Human-readable message", "error_details": [ { "attribute": "field_name", "message": "specific error" } ] } ``` `error_details` only appears for model validation failures. servers: - url: https://formhug.ai security: [] tags: - name: Forms description: Form CRUD - name: Attachments description: >- 2-step upload for form-element images (theme, rich-text, or field-element images). Prepare returns an `upload_id`; consume it in a theme update, attachment_commitments, or the form `fields` payload depending on purpose. - name: Entries description: Entries collected by a form owned by the current user - name: Folders description: Folder CRUD - name: Participated Forms description: Forms the current user has submitted to (does not own) - name: Published Form Entries description: Submit entries to a published form - name: Published Forms description: Read a published form's public structure for filling - name: Linked Form Options description: >- Discover candidate entries (and their `entry_token`s) for a `linked_form` field while filling a published form - name: Entry Attachments description: >- 2-step upload for `attachment` field submissions. Prepare returns an `upload_id`; submit it under the attachment field in `field_values` when creating the entry. - name: Me description: Current authenticated user - name: Webhooks description: Webhook integrations attached to a form - name: Form Themes description: Read and update a form's visual theme - name: Form Settings description: >- Per-form settings — submission flow, availability, access control, presentation - name: Field Rules description: >- Read and replace a form's conditional field-display and post-submission redirect rules. - name: Form Folder description: Per-user folder placement for a shared form - name: OAuth description: OAuth 2.0 PKCE token issuance and revocation paths: /api/v1/f/{form_token}/entry_attachments: parameters: - name: form_token in: path description: Form token required: true schema: type: string post: tags: - Entry Attachments summary: Prepare an entry-attachment upload description: > Prepare an upload for an `attachment` field. Returns a one-time `upload_id` and an `upload_url`. Send the file to `upload_url` with an HTTP `PUT`: the raw file bytes as the request body and the `Content-Type` header set to the value you declared in `content_type` (it must match). Use the `upload_url` exactly as returned. Then submit the returned `upload_id` under the attachment field in `field_values` when creating the entry — the entry-create endpoint registers the attachment. No PAT scope required. parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/EntryAttachmentInitRequest' responses: '200': description: Init for an `attachment` field inside a `table` field (tabular) content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/EntryAttachmentInit' '400': description: Content type not allowed by the field's `media_type` configuration content: application/json: examples: invalid_field_type: value: error: Field is not an attachment field bad_mime: value: error: Disallowed content type media_type_mismatch: value: error: >- Content type "application/pdf" is not allowed by the field's `media_type` configuration schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Tabular field but dimension_api_code does not match any dimension content: application/json: examples: field_not_found: value: error: Field not found schema: $ref: '#/components/schemas/ErrorEnvelope' '413': description: File exceeds field.max_size content: application/json: examples: too_large: value: error: 'File too large (field max_size: 20 MB)' schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: Storage backend is not S3/R2 (Qiniu-only deployment) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - PersonalAccessToken: [] components: schemas: EntryAttachmentInitRequest: type: object required: - field_api_code - file_name - content_type - file_size additionalProperties: false properties: field_api_code: type: string description: api_code of the target `attachment` field on this form. example: field_3 dimension_api_code: type: string description: >- api_code of the matrix/table dimension when the target field is tabular (e.g. file column inside a table field). Omit for non-tabular `attachment` fields. example: col_a file_name: type: string description: Original file name (with extension). example: design.pdf content_type: type: string description: >- MIME type. Must satisfy the field's `media_type` configuration and not be in the global blacklist (text/html, text/css, text/javascript, application/x-httpd-php). example: application/pdf file_size: type: integer description: File size in bytes. Must be ≤ `field.max_size * 1MB`. example: 5242880 EntryAttachmentInit: type: object required: - upload_id - upload_url - expires_at - field_api_code description: >- Prepare-step response for the 2-step entry-attachment upload. Send the file to `upload_url` with an HTTP PUT: the raw file bytes as the request body and the `Content-Type` header set to the value you declared in `content_type` (it must match). Use `upload_url` exactly as returned. Then submit the `upload_id` under the matching attachment field in `field_values` when creating the entry — the entry-create endpoint registers the attachment. `upload_id` is a self-describing handle (`.[.].`). properties: upload_id: type: string description: One-time id. Submit unchanged under field_values[field_api_code]. upload_url: type: string format: uri description: >- URL to upload the file to with an HTTP PUT (raw file bytes as the body, `Content-Type` matching the declared value). Use it exactly as returned. expires_at: type: string format: date-time description: When the upload credential expires (UTC, ISO 8601). field_api_code: type: string description: Echo of the target attachment field api_code. dimension_api_code: type: string nullable: true description: >- Echo of the matrix/table dimension api_code (null for non-tabular fields). ErrorEnvelope: type: object required: - error properties: error: type: string description: Error message securitySchemes: PersonalAccessToken: type: http scheme: bearer bearerFormat: PAT description: > Personal Access Token prefixed with `fh_`. Sent as `Authorization: Bearer fh_xxx`. The scope required by each endpoint is listed in that endpoint's description. ````