---
title: "Ask a person for files"
method: POST
path: "/uploads"
tags: ["Media"]
---

# Ask a person for files

`POST /uploads`

## Request

- Base URL: `https://api.rizamo.com/v1`
- URL: `https://api.rizamo.com/v1/uploads`
- Auth: HTTP bearer

Returns a page to give a person. They add images or videos there, no sign-in needed, and send them. Follow `status` with Get an upload request; its `media` are ready to use on a post. The page works for 24 hours.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `note` string: What you need, shown on the page: "The photos from Saturday's tasting".
  - `maxFiles` integer: How many files the person may add, up to 20: 10 when left out.
  - `profileId` string: Optional: a profile you reach, which the media joins at once. Left out, the media is yours (the person, key or agent that added it) until a post uses it, and then joins that post's profile.

## Response `201`

OK

- UploadRequest
  - `id` string, required
  - `status` 'open' | 'done' | 'expired', required: done: the person sent their files. expired: 24 hours went by.
  - `note` string, required
  - `maxFiles` integer, required
  - `media` Media[], required: The files the person added so far, ready to put on a post.
    - `id` string, required
    - `type` 'image' | 'video' | 'document', required: document: a PDF, which LinkedIn publishes as a document post.
    - `url` string, nullable, required: A link that expires after a few hours: get the media again for a fresh one. Null until the file is uploaded.
    - `alt` string, required
    - `status` 'uploading' | 'ready' | 'failed', required: uploading: waiting for its file. Only ready media can go on a post.
    - `contentType` string, required
    - `size` integer, required: Bytes, once uploaded.
    - `width` integer, nullable, required: Pixels, as shown: read from the file once it is uploaded.
    - `height` integer, nullable, required
    - `duration` number, nullable, required: Seconds, for video.
    - `pages` integer, nullable, required: Pages, for a PDF: read from the file once it is uploaded. Null when they could not be read.
    - `profileId` string, nullable, required: The profile it belongs to: the one it was added for, or else the first post that used it. Null until then, when only whoever added it and people who reach every profile reach it. Keys and people limited to some profiles reach their own media and their profiles'.
  - `profileId` string, nullable, required: The profile the files join at once. Null when the request named none: the files are then the asker's until a post uses them.
  - `url` string, nullable, required: The page to give the person. Only in the answer that creates the request.
  - `expiresAt` string, date-time, required

## Other responses

- `400`: `invalid_request`: A field is missing or wrong, or the request cannot be done as asked: the message names the field or says what to change.
- `401`: `unauthorized`: No API key or sign-in, or the key does not work: it was deleted, or it expired.
- `403`: `forbidden`: The caller may not do this: the key or agent lacks the scope (the message names it), or the action needs another role or a fresh sign-in.
- `404`: `not_found`: No such object, or it is outside your team or the profiles your key reaches.
- `409`: `conflict`: The object's state does not allow it now, such as an account that needs a new login. `queue_empty`: A post with `queue: true` whose profile has no posting times: set them, or give a `scheduledAt`. `queue_full`: No posting time free for the post's accounts in the next 90 days: add times, or give a `scheduledAt`. `idempotency_key_in_use`: A request with this `Idempotency-Key` is still running: try again in a moment.
- `413`: `payload_too_large`: The body is over 1 MB: files go up through the upload links of `POST /v1/media`.
- `415`: `unsupported_media_type`: The body is not JSON: send it with `Content-Type: application/json`.
- `422`: `capability_missing`: The account cannot do this: see its `capabilities`. `idempotency_key_reused`: This `Idempotency-Key` was used for a different request in the last 24 hours: send a new key.
- `429`: `rate_limited`: Over one of Rizamo's limits, or a network asked Rizamo to slow down: wait for `Retry-After` seconds, or as long as the message says.
- `500`: `internal`: Our side failed: retry, and send the `requestId` if it keeps failing.
- `503`: `timeout`: The request took too long to work out, most often a report: try again in a moment, or ask a report for a shorter period or one profile.

---

[API](https://skmtc.dev/rizamo/apis/rizamo-api.md) - [All operations](https://skmtc.dev/rizamo/apis/rizamo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rizamo/apis/rizamo-api/revisions/31b0c1b1ffb5?raw)
