> ## Documentation Index > Fetch the complete documentation index at: https://postmesh.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Add a file > Adds a file to your media library: send `path` once you uploaded it to a link from POST /media/uploads (it is checked to be the image or video it says), or `url` for PostMesh to download it. Put the answer's media_ref in a post's media. Needs an API key with the `media` scope. ## OpenAPI ````yaml /openapi.json post /media openapi: 3.1.0 info: title: PostMesh API version: 1.0.0 description: >- The PostMesh API posts, schedules and reads your posts on every network you connected, with JSON in and out. **Authentication.** Send an API key from Settings, API & MCP as `Authorization: Bearer pm_live_...`. Each key has scopes (read, drafts, publish, media); every endpoint says which it needs. **Retries.** Send an `Idempotency-Key` header (up to 255 printable characters, a UUID is ideal) with every POST. Sending the same key again within 24 hours answers with the first request's status and body instead of posting twice, and says so with `Idempotent-Replayed: true`. A request still running under the key answers 409; one that failed with a 5xx or 429 frees the key, so the retry runs. The same key with a different body is refused with 422. **Rate limits.** Each key may make 120 requests a minute. Every answer carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix seconds); a 429 also carries `Retry-After`. Posting and uploads have their own, smaller limits. **Errors.** A refusal is JSON with `error` (plain words) and `code` (stable, to act on). servers: - url: https://postmesh.app/api/v1 security: - apiKey: [] tags: - name: Posts description: Send, schedule, change and read posts. - name: Drafts description: Posts saved for later. - name: Media description: Images and videos for posts. - name: Accounts description: Your connected accounts and your plan. - name: Analytics description: How your posts did. paths: /media: post: tags: - Media summary: Add a file description: >- Adds a file to your media library: send `path` once you uploaded it to a link from POST /media/uploads (it is checked to be the image or video it says), or `url` for PostMesh to download it. Put the answer's media_ref in a post's media. Needs an API key with the `media` scope. operationId: createMedia parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMedia' responses: '201': description: Added. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/MediaAnswer' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/Unavailable' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Makes a retry safe: the same key within 24 hours answers with the first request's result. Up to 255 printable characters. schema: type: string minLength: 1 maxLength: 255 schemas: CreateMedia: anyOf: - type: object properties: path: type: string minLength: 1 maxLength: 512 description: The path POST /media/uploads gave, once the file is uploaded. name: type: string minLength: 1 maxLength: 255 required: - path additionalProperties: false - type: object properties: url: type: string maxLength: 2048 format: uri description: A public https link to an image or video, up to 80 MB. name: type: string minLength: 1 maxLength: 255 required: - url additionalProperties: false description: >- Adds a file to your media library: one you uploaded (path), or one PostMesh downloads (url). MediaAnswer: type: object properties: media: $ref: '#/components/schemas/Media' required: - media additionalProperties: false Media: type: object properties: id: anyOf: - type: string format: uuid - type: 'null' description: >- The media library id, for media_ids. Null when the file isn't in the library. media_ref: type: object properties: path: type: string name: type: string mime_type: type: string required: - path - name - mime_type additionalProperties: false description: Put this in a post's media. kind: type: string enum: - image - video size_bytes: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' width: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' height: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' duration_ms: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' alt_text: type: string source: type: string enum: - upload - api - clip_factory - ai_image url: description: A short-lived link to view the file. anyOf: - type: string - type: 'null' duplicate: description: 'The library had this file already: media_ref is that copy.' type: boolean const: true created_at: type: string format: date-time required: - id - media_ref additionalProperties: false description: A file in your media library. Error: type: object properties: error: type: string description: What went wrong, in plain words. code: type: string description: >- A stable code to act on, such as invalid_request, rate_limited or idempotency_key_reused. field: description: The request field that was refused. type: string retry_after: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - error - code additionalProperties: false description: Every refusal looks like this. headers: X-RateLimit-Limit: description: Requests this key may make in a minute. schema: type: integer X-RateLimit-Remaining: description: Requests left this minute. schema: type: integer X-RateLimit-Reset: description: When the minute resets, in Unix seconds. schema: type: integer responses: BadRequest: description: >- The request was refused: a field is missing or invalid. `field` names it. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: No API key, or one that isn't valid any more. content: application/json: schema: $ref: '#/components/schemas/Error' PaymentRequired: description: Your plan doesn't include this, or it has ended. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The key can't do this: it needs another scope (`code` is `api_key_scope`), or it is in approval mode. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The item changed since you read it, is being sent right now, or a request with this Idempotency-Key is still running. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' Unprocessable: description: This Idempotency-Key was already used for a different request. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Too many requests. Wait for `Retry-After` seconds. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: description: Seconds to wait. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' Unavailable: description: PostMesh can't answer right now. Try again shortly. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer description: 'An API key from Settings, API & MCP: pm_live_...' ```` ## Related topics - [MCP tool reference](https://postmesh.app/docs/mcp-tools.md) - [Pre-flight checks before every post](https://postmesh.app/docs/pre-flight-checks.md) - [Get a file](https://postmesh.app/docs/api-reference/media/get-a-file.md) - [PostMesh docs](https://postmesh.app/docs/index.md) - [Post to Discord with a channel webhook](https://postmesh.app/docs/discord.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.