aVenture APIMedia

Convert media asset

View as Markdown

Reprocesses an external source URL, existing managed source path, or the current attached entity/person/news image through imgproxy, stores the normalized asset, and attaches it to the selected media slot.

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:
sourceUrlstringOptionalformat: "uri"

External http(s) image URL to fetch through the backend image-fetch guard before imgproxy normalization.

sourcePathstringOptional

Existing managed storage path or API CDN URL to reprocess through imgproxy. This may point at a legacy raw object; the converted result must satisfy the configured final media profile before attachment.

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. Ignored for news thumbnails (wide by design). Blank or invisible images are always rejected regardless of this flag.

permitNearFloorWordmarkbooleanOptionalDefaults to false

For entity logos, permits a high-confidence page wordmark slightly below the minimum square icon dimensions, matching the near-floor exception granted at initial import. Ignored for person photos and news thumbnails. Default false rejects below-minimum images. Blank or invisible images are always rejected regardless of this flag.

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.

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
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error