> ## Documentation Index > Fetch the complete documentation index at: https://docs.isnap.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get an attachment > Returns an attachment and, when it is ready, a download URL valid 15 minutes. * **Credential:** an API key. A trial key returns `401 unauthorized`. An API key reads the attachments that its account created, and the files received on the inbound messages of its lines. * **Line-scoped keys:** the list of a [line-scoped key](/authentication#line-scoped-keys) is not applied: such a key reads every attachment the account can read. * **Events:** none. * **Personal data:** `filename` and the file behind `download_url` can hold personal data. Request them only when needed, do not copy them into logs, tickets or other tools, and refer to a contact by an id of your own. Treat `download_url` as a secret for as long as it is valid. * **Download URL:** `download_url` is set only when `status` is `ready`, and is valid until `download_expires_at`, 15 minutes later. Call the operation again for a new URL. See [Downloading a file](/guides/attachments#downloading-a-file). * **Waiting:** iSnap checks for an uploaded file every 30 seconds. Read this operation until `status` is `ready` before you send the attachment. See [Statuses](/guides/attachments#statuses). ## Errors | Status | `error.code` | When | | - | - | - | | 404 | `not_found` | The id is unknown, or the attachment is not one your account can read. | | 410 | `attachment_expired` | `expires_at` has passed: 72 hours after the attachment was created, or after iSnap registered a received file. | The errors that every operation shares are in [Errors](/errors-and-rate-limits#errors). ## OpenAPI ````yaml GET /v1/attachments/{id} openapi: 3.0.0 info: title: iSnap API version: 2.45.0 description: >- The iSnap API sends and receives iMessage, RCS and SMS on real phone lines, manages those lines, and reports events through webhooks. Every message is sent to a real recipient, with an `isnap_live_` key and with an `isnap_test_` key alike. Retry a `429` after `Retry-After` seconds. Retry a `500` or a `503` up to 2 times, with exponential backoff. Do not retry any other `4xx`: fix the request. Retry a write only on an operation that honors `Idempotency-Key`, with the key of the first attempt. Responses carry personal data: handles, names and message text. servers: - url: https://api.isnap.ai security: - bearerAuth: [] paths: /v1/attachments/{id}: get: summary: Get an attachment description: >- Returns one attachment and, when its `status` is `ready`, a signed `download_url` valid for 15 minutes: until `download_expires_at`. Call again for a new URL. For any other `status`, `download_url` and `download_expires_at` are `null`. An account can read the attachments it created and the files received on its inbound messages: any other id returns `404 not_found`. Once `expires_at` has passed, 72 hours after the attachment was created, or after iSnap registered a received file, the API returns `410 attachment_expired` and iSnap deletes the file. No event announces a change of `status`. Accepts an API key. The `line_ids` of a line-scoped key are not checked: the key reads every attachment the account can read. `filename` can carry personal data. parameters: - schema: type: string description: 'Attachment id: `att_` followed by 25 letters or digits.' required: true description: 'Attachment id: `att_` followed by 25 letters or digits.' name: id in: path responses: '200': description: >- The attachment, with a new `download_url` when its `status` is `ready`. content: application/json: schema: type: object properties: success: type: boolean enum: - true description: Always `true` on a success response. data: $ref: '#/components/schemas/Attachment' trace_id: type: string description: >- Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap. request_id: type: string description: >- Id of the request that produced this response: `req_` followed by 25 letters or digits. required: - success - data - trace_id - request_id '400': description: >- Invalid request. `error.code` is `validation_failed` when a parameter, a header or the body does not match its schema: `error.issues` then lists each problem. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: No valid credential. `error.code` is `unauthorized`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- Not found. `error.code` is `not_found`: the attachment does not exist, or it is neither an attachment your account created nor a file received on one of its inbound messages. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: >- Too many requests. `error.code` is `rate_limit_exceeded` when more than 100 requests came from the same network address in 60 seconds, whatever their API key or account: wait `error.retry_after` seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: >- Unexpected failure. `error.code` is `internal_error`. An operation that takes a JSON body also returns it when the body, sent as `application/json`, is not valid JSON. Quote `trace_id` when you report it to iSnap. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - bearerAuth: [] components: schemas: Attachment: type: object properties: id: type: string description: 'Attachment id: `att_` followed by 25 letters or digits.' filename: type: string description: File name. It can carry personal data. content_type: type: string description: >- Content type declared when the attachment was created. `audio/x-caf` once iSnap has converted an audio file. size_bytes: type: integer minimum: 1 description: >- Size in bytes declared when the attachment was created. For an audio file that iSnap converted, the size after conversion. status: type: string description: >- `awaiting_upload`: created, and iSnap has not seen the file. `transcoding`: iSnap is converting an audio file. `ready`: the file can be sent in a message and downloaded. `failed`: no file arrived before the upload deadline, or the conversion of an audio file failed, which is always the case above 52,428,800 bytes (50 MiB). Once `expires_at` has passed, the attachment is not returned: the API returns `410 attachment_expired`. download_url: type: string nullable: true format: uri description: >- Signed URL of the file, valid for 15 minutes. `null` unless `status` is `ready`. download_expires_at: type: string nullable: true description: >- When `download_url` stops working. `null` unless `status` is `ready`. duration_ms: type: integer nullable: true minimum: 0 description: >- Duration in milliseconds of an audio file that iSnap converted. `null` on every other file. created_at: type: string description: >- When the attachment was created: for a file received on an inbound message, when iSnap registered it. uploaded_at: type: string nullable: true description: >- When iSnap saw the uploaded file. `null` until then, and on the attachment of a contact card that `POST /v1/chats/{chat_id}/share-contact-card` creates, which is `ready` from the start. expires_at: type: string description: >- 72 hours after `created_at`. From this time the API returns `410 attachment_expired` for the attachment and iSnap deletes its file. warnings: type: array items: type: string description: >- Contains `large_attachment_may_delay_delivery` when the declared size is above 100,000,000 bytes. Empty otherwise. required: - id - filename - content_type - size_bytes - status - download_url - download_expires_at - duration_ms - created_at - uploaded_at - expires_at - warnings description: A file sent or received with a message. Timestamps are ISO 8601 in UTC. ErrorEnvelope: type: object properties: success: type: boolean enum: - false description: Always `false` on an error response. data: nullable: true description: Always `null` on an error response. error: type: object properties: status: type: integer description: The HTTP status of the response. code: type: string description: >- Stable machine-readable code that names the refusal. Branch on this value. message: type: string description: >- Text for a person. It can change between versions: do not branch on it. retry_after: type: integer nullable: true description: >- Seconds to wait before the next attempt. Set on the `429` responses that know a delay, where the `Retry-After` header carries the same value. When it is above 60 seconds, do not wait in a request: schedule the call, or report the time. `null` on every other error. retry_at: type: string nullable: true description: >- ISO 8601 timestamp at which the refusal ends. Set only on `429 rebind_cap_reached`. `null` on every other error. issues: type: array nullable: true items: type: object properties: path: type: array items: anyOf: - type: string - type: number description: >- Where the problem is: the field names and array indexes that lead to it. message: type: string description: Text for a person. code: type: string description: >- Kind of problem. On `validation_failed`, for example `invalid_type`, `invalid_value`, `invalid_format`, `invalid_union`, `invalid_key`, `invalid_element`, `too_small`, `too_big`, `not_multiple_of`, `unrecognized_keys` or `custom`. The list is open: read `path` and `message`. min: type: integer description: >- Smallest accepted value. Present only on `limit_out_of_bounds`, `mac_quantity_not_a_pack`, `byop_reduction_strands_mac_sessions` and `byop_reduction_strands_byod_lines`. max: type: integer description: >- Largest accepted value. Present only on `limit_out_of_bounds` and `mac_sessions_exceed_byop_lines`, and on the `too_big` issue of an `Idempotency-Key` header longer than 255 characters. required: - path - message - code description: >- Problems found in the request, one entry each. Set on most `400 validation_failed` responses and on the refusals that name a field: a refused `handle` of `POST /v1/lookup` has `issues: null`. `null` on every other error. required: - status - code - message - retry_after - retry_at - issues description: >- What went wrong. The six fields are always present; `retry_after`, `retry_at` and `issues` are `null` when they do not apply. trace_id: type: string description: >- Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap. request_id: type: string description: >- Id of the request that produced this response: `req_` followed by 25 letters or digits. required: - success - data - error - trace_id - request_id description: The body of an error response. securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key created in the iSnap dashboard, or a trial key, sent as `Authorization: Bearer `. An API key starts with `isnap_live_` or `isnap_test_`; both act on the same account, lines and billing. A trial key acts on its trial only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.