Register an external image reference
POST
/open/v1/media/references
const url = 'https://api.harperharbor.com/open/v1/media/references';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"url":"https://example.com","roleId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.harperharbor.com/open/v1/media/references \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com", "roleId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'HarperHarbor metadata-only operation. Requires role.write and a permitted image host; does not download image bytes. Optional roleId places the reference with an agent configuration owned by the caller, allowing synchronization across application tenants. The URL is resolved only as an owned media asset when attached.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Media typeapplication/json
object
url
required
string format: uri
roleId
string format: uuid
Examplegenerated
{ "url": "https://example.com", "roleId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}Responses
Section titled “Responses”Created or reused an owned reference. Returns assetId and url.
Invalid request or image source.
Unauthorized.
Missing role.write scope.
Target agent configuration is missing or not owned by caller.