---
title: "Upload new file"
method: POST
path: "/organizations/{id_organization}/uploads"
tags: ["uploads"]
---

# Upload new file

`POST /organizations/{id_organization}/uploads`

## Request

- Base URL: `https://api.planvortex.com/v1.0.0`
- URL: `https://api.planvortex.com/v1.0.0/organizations/{id_organization}/uploads`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (client credentials, token URL `https://api.planvortex.com/v1.0.0/oauth/token`)

Upload new file to the received organization

## Path parameters

- `id_organization` string, required

## Response `200`

Successful operation

- UploadsUploadOne
  - `upload` Upload, required: A file in the organization's library. **`public_path` is a signed, temporary URL, not a permanent link.** Do not store it: it expires. Ask for the upload again when you need it.
    - `_id` string, required
    - `id_organization` string, required
    - `name` string, required
    - `file_type` 'video' | 'image', required
    - `file_format` 'mp4' | 'jpeg' | 'gif' | 'png' | 'jpg', required: The format of the stored bytes. `heic`/`heif` are accepted at the door — that is what an iPhone produces — but never stored: they are converted to JPEG while being ingested, so an upload never comes back with one.
    - `file_properties` FileProperties, required: Measurements taken when the file was ingested. Always present on an upload.
      - `width` integer, required: `0` on a file whose dimensions could not be read.
      - `height` integer, required
      - `duration` integer, required: Seconds. `0` on an image.
      - `size_in_bytes` integer, required
      - `aspect_ratio` object, required: Width divided by height, as a number and as a person writes it.
        - `value` number, required
        - `text` string, required
      - `allowed_social_networks` string[], required: The networks whose accepted crops this file's ratio matches, with a 0.1 margin. It is about the RATIO only: a network listed here can still reject the file for its duration or its weight (see `GET /social_limits`).
    - `file_externals` object[], required: Where this file ended up on each network it has been published to. Some networks keep their own copy and give it an identifier that is reused instead of uploading the bytes again.
      - `social_network` 'facebook' | 'instagram' | 'linkedin' | 'tiktok' | 'twitter' | 'whatsapp' | 'youtube' | 'google_business' | 'bluesky' | 'discord' | 'telegram' | 'threads' | 'slack' | 'pinterest', required: A social network supported by PlanVortex. **This list grows.** Treat it as an open enumeration: a client that rejects an unknown value breaks the day a network is added, which happens several times a year. Not every network does everything — ask `GET /social_capabilities`.
      - `external_identifier` string, required
      - `external_url` string, required
    - `cover_image` Upload (recursive)
    - `cover_offset` integer: Point of the video, in milliseconds, used as the cover frame.
    - `ai_generated` AiImageOrigin: Where an AI-generated image came from. **Only images a model generated carry it**: a photo the organization uploaded, a product photo pulled from a connected shop or an image imported from an integration never does. It is set when the image is generated and cannot be edited. Use it to show your own AI label: under article 50(4) of the EU AI Act, telling the audience that an image is AI-generated is the job of whoever publishes it. Images made with the default model also carry a signed C2PA manifest, IPTC metadata and a SynthID watermark in the file itself. PlanVortex keeps the IPTC marker when it crops or recompresses an image for a network; the C2PA signature does not survive a change of pixels.
      - `provider` string, required: The AI provider that answered: `openrouter` unless the client brought its own key.
      - `model` string, required: The model, as it was requested, for instance `google/gemini-3.1-flash-image`.
      - `generated_at` string, date-time, required
      - `id_ai_plan` string: The AI plan that generated it.
    - `is_temporal` boolean, required: `true` on a file the platform created for itself — a crop made to fit a network's aspect ratio. Temporary files are not part of the library listing.
    - `public_path` string, uri, required: Download URL. IMPORTANT: it is a TEMPORARY, signed URL, not a permanent link. It expires (24 hours by default) and must not be stored or shared: ask for the upload again to get a valid one. The URL stays byte-identical within the same hour, so it can be cached for that long.
    - `creation_date` string, date-time, required

## Other responses

- `400`: The request failed. The body carries the PlanVortex error code in `code`: | Code | Meaning | | --- | --- | | `1101` | Invalid organization | | `804` | Max folder size reached per organization | | `800` | Invalid image format file, only allow: JPEG, PNG, BMP, GIF, JPG | | `801` | Invalid video format, only mp4 allowed | | `802` | Invalid image size, max allowed 5mb | | `803` | Invalid video size, max allowed 512mb | | `805` | Invalid file type, only allow videos and images | | `809` | Only videos con have a thumbnail image | | `810` | Thumbnail must be an image | | `523` | Invalid application |
- `500`: Unhandled error by the server

---

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