---
title: "Import a photo from a URL, or get a presigned PUT ticket for a local file"
method: POST
path: "/api/v1/uploads"
tags: ["Uploads"]
---

# Import a photo from a URL, or get a presigned PUT ticket for a local file

`POST /api/v1/uploads`

## Request

- Base URL: `https://pixly.app`
- URL: `https://pixly.app/api/v1/uploads`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://pixly.app/oauth/authorize`, token URL `https://pixly.app/api/oauth/token`, scopes: `tools`)

## Request body

- union
  - object
    - `url` string, uri, required
  - object
    - `filename` string, required
    - `contentType` 'image/jpeg' | 'image/png' | 'image/webp' | 'image/heic' | 'image/heif' | 'image/tiff', required
    - `sizeBytes` integer

## Response `201`

r2Path always; a ticket also carries uploadUrl (PUT the bytes there) and imageUrl (pass to any tool)

- object
  - `r2Path` string, required
  - `uploadUrl` string
  - `imageUrl` string
  - `note` string

## Other responses

- `401`: Missing/invalid credential
- `402`: Out of credits, or no active subscription (error.required = credits needed) — POST /api/v1/checkout returns a payment link
- `422`: Invalid input — error.issues lists the offending fields
- `429`: Rate limited — see Retry-After (120 req/min, 30/min for generations)

---

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