{"openapi":"3.1.0","info":{"title":"Amaposta API","description":"Upload images and videos, create posts and schedule them across every connected channel.\n\nAuthenticate with `Authorization: Bearer <API key>`. Errors share one shape: `{\"error\": {\"code\", \"message\", \"fields\"?, \"hint\"?}}`. Rate limit: 120 requests per minute per key.","license":{"name":""},"version":"1.0.0"},"paths":{"/api/v1/me":{"get":{"tags":["Account"],"summary":"Who am I? Returns the key's workspace, scopes and accessible projects.","operationId":"me","responses":{"200":{"description":"Key details","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[{"api_key":[]}]}},"/api/v1/media/{media_id}":{"get":{"tags":["Media"],"operationId":"get_media","parameters":[{"name":"media_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Media"}}}}},"security":[{"api_key":[]}]}},"/api/v1/media/{media_id}/complete":{"post":{"tags":["Media"],"summary":"Finish a presigned upload.","operationId":"complete_media","parameters":[{"name":"media_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Media"}}}}},"security":[{"api_key":[]}]}},"/api/v1/posts/{post_id}":{"get":{"tags":["Posts"],"operationId":"get_post","parameters":[{"name":"post_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Post"}}}}},"security":[{"api_key":[]}]},"delete":{"tags":["Posts"],"operationId":"delete_post","parameters":[{"name":"post_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"}},"security":[{"api_key":[]}]}},"/api/v1/posts/{post_id}/schedule":{"post":{"tags":["Posts"],"summary":"Schedule, publish now, add to the queue, or unschedule.","operationId":"schedule_post","parameters":[{"name":"post_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Schedule"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Post"}}}}},"security":[{"api_key":[]}]}},"/api/v1/projects":{"get":{"tags":["Projects"],"operationId":"list_projects","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Project"}}}}}},"security":[{"api_key":[]}]}},"/api/v1/projects/{project_id}/channels":{"get":{"tags":["Projects"],"operationId":"list_channels","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/V1Channel"}}}}}},"security":[{"api_key":[]}]}},"/api/v1/projects/{project_id}/media":{"post":{"tags":["Media"],"summary":"Upload a file directly (multipart form, field `file`). Best for files up to a few hundred MB.","operationId":"upload_media","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"description":"Form with a `file` field","content":{"multipart/form-data":{}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Media"}}}}},"security":[{"api_key":[]}]}},"/api/v1/projects/{project_id}/media/import":{"post":{"tags":["Media"],"summary":"Have Amaposta download a file from a public URL.","operationId":"import_media","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UrlImport"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Media"}}}}},"security":[{"api_key":[]}]}},"/api/v1/projects/{project_id}/media/uploads":{"post":{"tags":["Media"],"summary":"Get a presigned URL to PUT a large file straight to storage.","operationId":"presign_media","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UploadRequest"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1UploadTicket"}}}}},"security":[{"api_key":[]}]}},"/api/v1/projects/{project_id}/posts":{"get":{"tags":["Posts"],"operationId":"list_posts","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"path","description":"Comma-separated statuses, or `inbox`, `queue`, `history`.","required":true,"schema":{"type":["string","null"]}},{"name":"from","in":"path","required":true,"schema":{"type":["string","null"],"format":"date-time"}},{"name":"to","in":"path","required":true,"schema":{"type":["string","null"],"format":"date-time"}},{"name":"limit","in":"path","required":true,"schema":{"type":["integer","null"],"format":"int64"}},{"name":"offset","in":"path","required":true,"schema":{"type":["integer","null"],"format":"int64"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1PostList"}}}}},"security":[{"api_key":[]}]},"post":{"tags":["Posts"],"summary":"Create a post (and optionally schedule it). Send an `Idempotency-Key` header to make retries safe.","operationId":"create_post","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Retries with the same key return the original post","required":false,"schema":{"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1PostInput"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1Post"}}}}},"security":[{"api_key":[]}]}}},"components":{"schemas":{"V1Channel":{"type":"object","required":["id","provider","name","status","supports"],"properties":{"handle":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"provider":{"type":"string","description":"youtube, instagram, tiktok, x, facebook, custom, sandbox"},"status":{"type":"string","description":"active, expiring, needs_reconnect, error, disabled"},"supports":{"type":"array","items":{"type":"string"},"description":"Post kinds this channel accepts."}}},"V1Delivery":{"type":"object","required":["id","channel_id","status"],"properties":{"channel_id":{"type":"string","format":"uuid"},"error":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/V1Error"}]},"id":{"type":"string","format":"uuid"},"published_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","description":"pending, scheduled, publishing, processing, published, failed, cancelled"},"url":{"type":["string","null"],"description":"Link to the live post once published."}}},"V1Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"hint":{"type":["string","null"]},"message":{"type":"string"}}},"V1Media":{"type":"object","required":["id","project_id","kind","status","content_type","created_at"],"properties":{"content_type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"duration_ms":{"type":["integer","null"],"format":"int32"},"error":{"type":["string","null"]},"height":{"type":["integer","null"],"format":"int32"},"id":{"type":"string","format":"uuid"},"kind":{"type":"string","description":"image or video"},"project_id":{"type":"string","format":"uuid"},"size_bytes":{"type":["integer","null"],"format":"int64"},"status":{"type":"string","description":"pending, processing, ready, failed"},"thumbnail_url":{"type":["string","null"]},"url":{"type":["string","null"],"description":"Signed URL, valid for 12 hours."},"width":{"type":["integer","null"],"format":"int32"}}},"V1Override":{"type":"object","required":["options"],"properties":{"description":{"type":["string","null"],"description":"Replaces the description/caption for this channel only."},"hashtags":{"type":["array","null"],"items":{"type":"string"}},"options":{"type":"object","description":"Provider-specific options (e.g. `{\"privacy\": \"unlisted\"}` for YouTube)."},"title":{"type":["string","null"],"description":"Replaces the title for this channel only."}}},"V1Post":{"type":"object","required":["id","project_id","kind","description","hashtags","status","review_state","deliveries","created_at"],"properties":{"cover_media_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/V1Delivery"}},"description":{"type":"string"},"external_ref":{"type":["string","null"],"description":"Your own reference, echoed back."},"hashtags":{"type":"array","items":{"type":"string"}},"id":{"type":"string","format":"uuid"},"kind":{"type":"string","description":"text, image or video"},"media_id":{"type":["string","null"],"format":"uuid"},"project_id":{"type":"string","format":"uuid"},"published_at":{"type":["string","null"],"format":"date-time"},"review_state":{"type":"string","description":"draft, in_review, changes_requested, approved"},"scheduled_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","description":"draft, in_review, changes_requested, ready, scheduled, publishing, published, partial, failed"},"title":{"type":["string","null"]}}},"V1PostInput":{"type":"object","required":["kind","metadata"],"properties":{"channels":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"Channel ids. Defaults to every active channel in the project that supports this kind."},"cover_media_id":{"type":["string","null"],"format":"uuid","description":"Cover image for videos (id or URL)."},"cover_url":{"type":["string","null"]},"description":{"type":["string","null"],"description":"Caption / description / post text."},"external_ref":{"type":["string","null"]},"hashtags":{"type":["array","null"],"items":{"type":"string"},"description":"With or without `#`."},"kind":{"type":"string","description":"text, image or video","example":"video"},"media_id":{"type":["string","null"],"format":"uuid","description":"An uploaded media id…"},"media_url":{"type":["string","null"],"description":"…or a public URL Amaposta downloads for you."},"metadata":{"type":"object","description":"Free-form JSON stored with the post. Include `\"pipeline\": {…}` to mark generated content."},"overrides":{"type":["object","null"],"description":"Per-channel overrides keyed by channel id.","additionalProperties":{"$ref":"#/components/schemas/V1Override"},"propertyNames":{"type":"string","format":"uuid"}},"schedule":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/V1Schedule","description":"Omit to create a draft."}]},"title":{"type":["string","null"],"description":"Used by platforms with a title field (YouTube, TikTok photos, Facebook video)."}}},"V1PostList":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/V1Post"}},"total":{"type":"integer","format":"int64"}}},"V1Project":{"type":"object","required":["id","name","slug","timezone","approval_required"],"properties":{"approval_required":{"type":"boolean","description":"Posts from keys without `posts:publish` wait for approval."},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone used for posting slots."}}},"V1Schedule":{"type":"object","required":["mode"],"properties":{"at":{"type":["string","null"],"format":"date-time"},"mode":{"type":"string","description":"`at` (requires `at`), `now`, or `queue` (next free posting slot).","example":"queue"}}},"V1UploadRequest":{"type":"object","required":["filename"],"properties":{"content_type":{"type":["string","null"]},"filename":{"type":"string"},"size_bytes":{"type":["integer","null"],"format":"int64","minimum":0}}},"V1UploadTicket":{"type":"object","required":["media","upload_url"],"properties":{"media":{"$ref":"#/components/schemas/V1Media"},"upload_url":{"type":"string","description":"PUT the file bytes here within 12 hours, with the `Content-Type` the file was announced\nwith, then call `POST /media/{id}/complete`."}}},"V1UrlImport":{"type":"object","required":["url"],"properties":{"filename":{"type":["string","null"]},"url":{"type":"string"}}}},"securitySchemes":{"api_key":{"type":"http","scheme":"bearer","bearerFormat":"ss_live_…","description":"Create keys in Settings → API & webhooks."}}},"tags":[{"name":"Projects"},{"name":"Media"},{"name":"Posts"},{"name":"Account"}]}