aVenture APIMedia

Upload media asset

View as Markdown

Uploads bytes to R2 and may attach the managed path; CLI/MCP URLs are fetched. Agent ENTITY and PERSON uploads must cite the exact source image in sourceDetail; PERSON images must be named headshot photos, not avatar CDNs.

Authentication

AuthorizationBearer

User bearer token: Supabase or Clerk session JWT, Clerk OAuth access token, or Clerk personal API key

OR
X-API-Keystring

Admin API key for system-to-system write operations

Query parameters

mediaTypeenumRequired
Media target type.
Allowed values:
idstringOptional

Target UUID for entity/person or integer id for news.

slugstringOptionalformat: "^[a-z0-9_-]+$"<=255 characters
Target slug.
logoTypeenumOptional
Entity logo variant.
Allowed values:
permitWidebooleanOptionalDefaults to false

Fallback that permits a wide (non-square) logo or photo into the square slot, used only after confirming no square or near-square source exists. Default false rejects wide wordmark/banner content for ENTITY/PERSON. Blank or invisible images are always rejected regardless of this flag.

overrideGateenumOptional
Gate to override from the prior ProblemDetail resolution.
overrideReasonstringOptional0-2048 characters

Source-backed reason for overriding the returned gate requirement.

sourceTypeenumRequired
Write provenance source type.
sourceDetailstringRequired
Source detail or reviewer reference for the write.
sourceProviderstringOptional

Provider name for provider-native IDs or slugs.

sourceProviderIdstringOptional

Provider-native source ID.

sourceProviderSlugstringOptional

Provider-native source slug.

actorTypeenumOptional

Actor type; inferred as agent when agentChassis and agentModel are supplied, or as employee from an authenticated user JWT session.

Allowed values:
agentChassisstringOptional

Agent chassis token for agent-authored writes.

agentModelstringOptional

Agent model id for agent-authored writes.

Request

This endpoint expects a multipart form containing a file.
filefileRequired

Image file to upload. CLI/MCP may supply a local file path or http(s) URL. Agent ENTITY/PERSON uploads require the exact source image; PERSON images cannot be avatar CDNs.

Response

OK
cdnUrlstring
Resolved API CDN URL
mediaTypeenum
Target media domain
pathstring

Attached managed storage path; never an external image URL

firstUploadedAtdatetime or nullOptional

Earliest recorded write timestamp for this media asset slot from res_provenance_event (when this entity/person/news first received any image in this slot).

provenanceobject or nullOptional

Latest write source for this media asset slot from res_provenance_event. changedAt is the last-modified timestamp of the current attached file.

targetIdstring or nullOptional

Attached entity/person/news target id, when known

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
406
Not Acceptable Error
409
Conflict Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error