Install

For agents — install the MCP server:

npx argus-media-mcp

For humans — sign in at argus.build/ui with your email. No password needed.

Authenticate

All API requests require a Bearer token.

Get an API key

1. Go to argus.build/ui
2. Sign in with magic link (email-based, no password)
3. Open Settings
4. Click Create API Key

Use it

curl https://argus.build/assets -H "Authorization: Bearer ak_yourkey"

Session auth (cookie-based) is used by the web UI. API keys are for agents and scripts.

Quick Start

Upload an image, wait for AI analysis, then search for it.

1. Upload

curl -X POST https://argus.build/assets/upload \
  -H "Authorization: Bearer ak_yourkey" \
  -F "file=@product-photo.jpg" \
  -F "project=spring-campaign" \
  -F "tags=product,lifestyle"

2. Check status

curl https://argus.build/assets/ASSET_ID \
  -H "Authorization: Bearer ak_yourkey"
# status: "pending" → "ready" once analysis completes

3. Search

curl "https://argus.build/assets?q=lifestyle+product" \
  -H "Authorization: Bearer ak_yourkey"

Assets

Upload, search, analyze, and delete media assets. Requires Bearer API key.

Soft delete & recovery: DELETE /assets/:id is a soft delete. The asset is hidden from default listings but can be recovered within 30 days via POST /assets/:id/recover. To list deleted assets, pass status=deleted on GET /assets. After 30 days, a scheduled purge permanently removes the asset and file.

Auth

Email-based magic link authentication. No password required. All routes are public.

Workspaces

Manage workspaces and team members. Requires session cookie (web UI auth).

API Keys

Create and revoke API keys for programmatic access. Requires session cookie.

Billing

Subscription upgrades and credit pack purchases via Stripe. Checkout routes are public; usage requires auth.

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.