Asset Analysis API

The Asset Analysis API runs AI-powered analysis over images and documents. It can answer a custom prompt about one or more assets, automatically generate and apply descriptive tags, and update an asset’s summary.

Vision analysis: JPEG, PNG, GIF, and WebP images.
Document analysis: Markdown, HTML, TXT, JSON, and CSV files.
Auto-tagging: generates and applies descriptive tags to assets.
Summaries: produces AI-generated descriptions and summary excerpts.

Authentication

Include your organisation credentials as headers:

X-Organization-Id: <your-organization-id>
X-Organization-Api-Key: <your-agent-api-key>

Or include them in the request body as organizationId and organizationApiKey.

Analyse assets

Analyse one or more assets with a custom prompt.

POST /api/assets/analyze

Request body

Field	Type	Required	Description
`prompt`	string	Yes	The question or analysis prompt.
`assetIds`	string[]	One of `assetIds`/`urls`	Asset IDs to analyse.
`urls`	string[]	One of `assetIds`/`urls`	External image URLs to analyse.
`autoTag`	boolean	No	Generate and apply tags. Defaults to `false`.
`updateSummary`	boolean	No	Update the asset’s summary excerpt. Defaults to `false`.
`maxTokens`	number	No	Maximum response tokens (100–4000). Defaults to 2000.

At least one of assetIds or urls must be provided.

Example request

curl -X POST https://api.runnit.io/api/assets/analyze \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -H "X-Organization-Api-Key: <your-agent-api-key>" \
  -d '{
    "assetIds": ["asset-uuid-1", "asset-uuid-2"],
    "prompt": "Describe what you see in these images and identify any people, objects, or text.",
    "autoTag": true,
    "updateSummary": true
  }'

Example with external URLs

curl -X POST https://api.runnit.io/api/assets/analyze \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -H "X-Organization-Api-Key: <your-agent-api-key>" \
  -d '{
    "urls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.png"
    ],
    "prompt": "Compare these two images and describe the differences."
  }'

Response

{
  "success": true,
  "response": "The image shows a modern office space with...",
  "assetResults": [
    {
      "assetId": "asset-uuid-1",
      "success": true,
      "response": "The image shows...",
      "tags": [
        { "name": "office", "confidence": 0.95 },
        { "name": "modern-design", "confidence": 0.88 }
      ]
    }
  ]
}

Generate tags for an asset

Generate and apply AI tags to a single asset.

POST /api/assets/:assetId/generate-tags

Path parameters

Parameter	Type	Description
`assetId`	UUID	The asset to generate tags for.

Example request

curl -X POST https://api.runnit.io/api/assets/<asset-id>/generate-tags \
  -H "X-Organization-Id: <your-organization-id>" \
  -H "X-Organization-Api-Key: <your-agent-api-key>"

Response

{
  "success": true,
  "description": "A vibrant sunset over a mountain landscape with snow-capped peaks.",
  "tags": [
    { "id": "tag-uuid-1", "name": "sunset", "slug": "sunset" },
    { "id": "tag-uuid-2", "name": "mountain", "slug": "mountain" }
  ],
  "rawTags": [
    { "name": "sunset", "confidence": 0.98 },
    { "name": "mountain", "confidence": 0.95 },
    { "name": "landscape", "confidence": 0.92 }
  ]
}

Supported formats

Images (vision analysis): JPEG/JPG, PNG, GIF, WebP.

Documents: Markdown (.md), HTML (.html, .htm), plain text (.txt), JSON (.json), CSV (.csv).

Error responses

// 400 Bad Request
{ "success": false, "error": "At least one assetId or url must be provided" }

// 401 Unauthorized
{ "success": false, "error": "Missing organization credentials" }

// 403 Forbidden
{ "success": false, "error": "Invalid organization API key" }

// 503 Service Unavailable
{ "success": false, "error": "AI analysis service is not available." }

Common use cases

Summarise a document: "Summarise this document in 3 bullet points."
Extract data from an image: "Extract the total amount, date, and vendor name from this receipt."
Compare versions: "Compare these two design versions. What changed between them?"
Auto-tag uploads: set autoTag: true and updateSummary: true to tag and summarise in one call.