API Overview

Clarento provides a REST API via Atlassian Forge webtriggers for querying assets and receiving external uploads.

Base URL

Your API base URL is a Forge webtrigger URL. Find it in your Forge app's installation details:

https://<app-id>.hello.atlassian-dev.net/x1/<install-id>/<webtrigger-key>

Authentication

Pass your API key via the X-Api-Key header:

curl -H "X-Api-Key: YOUR_KEY" "https://your-webtrigger-url?q=logo"

Alternatively, pass it as a query parameter: ?apiKey=YOUR_KEY

The API key is configured as a Forge environment variable (CLARENTO_API_KEY). If no key is configured, the API is open (development mode only — not recommended for production).

Response Format

All responses are JSON with a _status field:

{
  "_status": 200,
  "assets": [],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Error Responses

Status	Meaning
401	Invalid or missing API key
404	Asset or collection not found
500	Internal server error

CORS

The API includes Access-Control-Allow-Origin: * headers, so it can be called from browser-side JavaScript.

Rate Limits

The API runs on Atlassian Forge, which has platform-level rate limits. For high-volume use cases, consider caching responses on your end.