# Attachments

## Initiate attachment upload

> Initiate an attachment upload by generating a presigned URL and signed token.\
> \
> This is phase 1 of the two-phase attachment flow:\
> 1\. Call this endpoint to get presigned URL and token\
> 2\. Upload file to the presigned URL\
> 3\. Pass token(s) when creating the entity (e.g., comment) to link attachments

```json
{"openapi":"3.1.0","info":{"title":"shade","version":"dev"},"paths":{"/attachments/upload":{"post":{"tags":["attachments"],"summary":"Initiate attachment upload","description":"Initiate an attachment upload by generating a presigned URL and signed token.\n\nThis is phase 1 of the two-phase attachment flow:\n1. Call this endpoint to get presigned URL and token\n2. Upload file to the presigned URL\n3. Pass token(s) when creating the entity (e.g., comment) to link attachments","operationId":"initiate_attachment_upload_attachments_upload_post","parameters":[{"name":"password","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"The password","description":"The password header to use to fetch the preview"},"description":"The password header to use to fetch the preview"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_initiate_attachment_upload_attachments_upload_post"}}}},"responses":{"200":{"description":"Presigned URL and token for uploading an attachment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentUploadResponse"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_initiate_attachment_upload_attachments_upload_post":{"properties":{"drive_id":{"type":"string","format":"uuid","title":"Drive ID","description":"The ID of the drive to upload the attachment to"},"size":{"type":"integer","title":"File size","description":"The size of the file in bytes"},"mime_type":{"type":"string","title":"MIME type","description":"The MIME type of the file"},"file_name":{"type":"string","title":"File name","description":"The original filename"},"entity":{"$ref":"#/components/schemas/AttachmentEntity","title":"Entity","description":"The entity that will own this attachment (e.g., 'comments')"},"body":{"additionalProperties":true,"type":"object","title":"Body","default":{}}},"type":"object","required":["drive_id","size","mime_type","file_name","entity"],"title":"Body_initiate_attachment_upload_attachments_upload_post"},"AttachmentEntity":{"type":"string","enum":["comments","assets"],"title":"AttachmentEntity"},"AttachmentUploadResponse":{"properties":{"presigned_url":{"type":"string","title":"Presigned Url"},"token":{"type":"string","title":"Token"}},"type":"object","required":["presigned_url","token"],"title":"AttachmentUploadResponse","description":"Response from attachment upload initiation."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://academy.shade.inc/developers/attachments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.