Response Shape

Every asset returned from the API includes this structure once analysis is complete.

{
  "id": "uuid",
  "filename": "photo.jpg",
  "mimeType": "image/jpeg",
  "url": "https://...",
  "status": "ready",
  "tags": ["outdoor", "nature"],
  "analysis": {
    "description": "A field of wildflowers at golden hour",
    "richDescription": "Detailed paragraph...",
    "mood": "serene",
    "dominantColors": [{ "hex": "#f5c842", "name": "golden yellow" }],
    "useCases": ["hero image", "seasonal campaign"],
    "tags": ["wildflowers", "golden hour", "landscape"]
  }
}

Field Notes

• tags Merged array of user-supplied tags and AI-generated tags (deduplicated).
• analysis.tags AI-generated tags only.

Error Responses

All error responses return a JSON object with an error string:

{ "error": "Description of what went wrong" }

Rate Limits

Argus uses tier-based limits (asset count and credits per month) rather than per-IP rate limiting.

• When limits are hit The API returns 429 with { "error": "...", "upgrade": true }. Check GET /usage for current consumption.
• No per-IP throttling There is no request-per-second or per-IP rate limit. You can call the API as fast as needed within your tier.
• Monthly reset Credit usage resets at the start of each billing cycle. One-time credit packs do not expire.

MCP Setup

Give your agent direct access to Argus with the MCP server.

npx argus-media-mcp

Claude Desktop / claude_desktop_config.json

{
  "mcpServers": {
    "argus": {
      "command": "npx",
      "args": ["argus-media-mcp"],
      "env": { "ARGUS_API_KEY": "<your-api-key>" }
    }
  }
}

Set ARGUS_BASE_URL to override the default https://argus.build if self-hosting.

MCP Tools

Nine tools available through the MCP server.

agents.txt

Machine-readable capability declaration at /agents.txt. Plain text, no auth required. Contains the full API reference, MCP tools, pricing, and limitations in a format optimized for LLM consumption.

Supported Formats

• AI-analyzed formats JPEG, PNG, GIF, WebP, SVG — these are processed by AI vision and receive full analysis (description, mood, colors, tags, use-cases)
• Other file types Any file can be uploaded and stored, but non-image files (PDFs, documents, etc.) are not analyzed. They are stored in R2 and immediately set to status: "ready" with no analysis data.
• Max upload size 20 MB per file
• Storage Cloudflare R2
• Analysis output Description, rich description, mood, dominant colors (hex + name), use-cases, tags, EXIF when available

Processing Time & Polling

AI analysis runs asynchronously after upload. The asset is returned immediately with status: "pending".

• Typical analysis time 5–15 seconds for most images
• How to check Poll GET /assets/:id until status changes to "ready" or "error". Recommended interval: every 2–3 seconds.
• Webhooks Not available. Polling is the only option.

Search Semantics

The q parameter on GET /assets performs keyword matching across AI-generated fields — not vector or embedding search.

• How it works Your query is split into terms. Each term is matched (case-insensitive substring) against the asset’s filename, description, rich description, mood, tags, and use-cases. Results are ranked by how many terms match.
• Why it feels semantic Because the fields being searched are AI-generated. A photo of a sunset will match “warm golden hour” if the AI used those words in its analysis — even though the search itself is keyword-based.
• Tip Use descriptive, natural-language terms rather than exact filenames for best results.

Pricing

1 credit = 1 AI image analysis. Credit packs: 100 for $2, 500 for $8, 2,500 for $30.

When NOT to Use Argus

• Video files Not supported. No analysis, no storage optimization.
• Real-time processing Analysis is async. Not suitable for synchronous pipelines.
• Non-image documents PDFs, docs, spreadsheets are stored but never analyzed.
• Self-hosted storage Argus uses Cloudflare R2. No bring-your-own-bucket option.
• Bulk migration No batch import API. Upload one at a time or use MCP in a loop.