DesignVaultDocs

Programmatic API

A public REST API to push assets into DesignVault, read and filter the library, and search it by meaning — from your automations, CI scripts, no-code integrations, or internal tools.

📖 Full interactive reference with cURL, JavaScript and Python examples: /api/v1/docs

Want a conversational interface instead of writing requests? The MCP server exposes this API to Claude, Cursor and other AI clients — search, browse and manage your library straight from a chat.

Auth

Per-organization bearer token. Generate a key under Settings → API keys → New key. The key is shown only once — copy it immediately into your secrets vault.

curl https://www.designvault.net/api/v1/tags \
  -H "Authorization: Bearer dv_live_xxxxxxxxxxxxxxxxxx"

Endpoints

MethodPathPurpose
POST/api/v1/assetsPush an asset (image + metadata)
GET/api/v1/assetsList / filter assets (paginated)
GET/api/v1/assets/{id}Fetch a single asset
POST/api/v1/searchHybrid full-text + semantic search
GET/api/v1/tagsList org tags (autocomplete)
GET/api/v1/asset-typesList org asset_type catalogue
GET/api/v1/collectionsList 20 most-recent collections

Scopes: assets:write covers everything; assets:read grants the read and search endpoints only.

Read the library

GET /api/v1/assets accepts the same filters as the in-app grid — asset_type, client, product, tag, full-text q — plus limit (max 100) and offset. Thumbnails come back as signed URLs valid ~24 h: re-fetch rather than store them.

curl "https://www.designvault.net/api/v1/assets?asset_type=banner_ad&q=q4+launch&limit=10" \
  -H "Authorization: Bearer dv_live_xxx"

Search by meaning

POST /api/v1/search runs the same hybrid engine as the in-app search: 0.4 × full-text rank + 0.6 × semantic cosine. If the organization has AI disabled, it degrades to full-text only — check the mode field (hybrid | text) instead of branching on errors.

POST /api/v1/search
Authorization: Bearer dv_live_xxx
Content-Type: application/json

{ "q": "dark hero with big type from the Q4 launch", "limit": 10 }

Push an asset

Two options: image_url (we fetch it with SSRF guards) or image_base64 (inline, capped at 25 MB).

POST /api/v1/assets
Authorization: Bearer dv_live_xxx
Content-Type: application/json

{
  "image_url": "https://cdn.example.com/banner-v3.png",
  "title": "Hero banner v3",
  "asset_type": "banner_ad",
  "client": "Acme Co",
  "tag_names": ["spring-2026", "hero"],
  "collection_name": "Q1 2026 campaign",
  "source_url": "https://www.figma.com/design/abc/file?node-id=123-456"
}

Response:

{
  "asset_id": "550e8400-e29b-41d4-a716-446655440000",
  "duplicate": false
}

Rate limits

EndpointLimitBucket
POST /api/v1/assets30/min/keyexpensive
POST /api/v1/search30/min/keyexpensive (one OpenAI embedding per hybrid call)
GET /api/v1/*120/min/keycheap

429 responses include Retry-After in seconds. Implement an exponential backoff in your client.

Common errors

  • 401 — missing, revoked, or expired key
  • 403 — insufficient scope (the key lacks assets:write), or plan limit reached
  • 404 — collection_name doesn't exist (no auto-creation — intentional, to avoid proliferation)
  • 413 — image > 25 MB
  • 502 — image_url blocked by SSRF guards or upstream down

SDK

No official SDK yet — the API is simple enough to consume directly. Any OpenAPI 3.1 generator can produce a client from our spec:

# TypeScript
npx openapi-typescript https://www.designvault.net/api/v1/openapi.json -o api.ts

# Python
openapi-python-client generate --url https://www.designvault.net/api/v1/openapi.json

Webhooks

To be notified when things change (assets created, collections shared, members joining…) instead of polling, subscribe to outbound webhooks. Eight events, HMAC-SHA256 signatures, automatic retries.

Versioning

The /api/v1 prefix is stable. Breaking changes will land under /api/v2 in parallel. We guarantee a 6-month minimum of coexistence before retiring a version.

Programmatic API — DesignVault Docs