API documentation

1. Quickstart

Every capability in the platform is reached through a single HTTPS endpoint. You do not choose a model or a service — you send content, and the API detects the modality and returns the analysis appropriate to it.

# Analyze an image — the modality is detected from the payload
curl -X POST https://api.visibilityzone.com/v1/analyze \
  -H "Authorization: Bearer $VZ_API_KEY" \
  -F file=@product.jpg

2. Authentication

Authenticate with a bearer token in the Authorization header. Keys are issued per environment (test and live) and can be rotated at any time from your account without downtime — old and new keys stay valid together during a rotation window you control.

Authorization: Bearer vz_live_<your-key>

Treat keys as secrets: never embed one in a browser, mobile app or public repository. Client-side calls should go through your own backend. You are responsible for all usage under your keys — see the Terms of Service.

3. The analyze endpoint

POST/v1/analyze

Accepts either multipart/form-data (for files) or application/json (for text-only requests). The modality is inferred from what you send; you can override it with the type parameter when you need to be explicit.

4. Image analysis

Returns labels, dominant colors, detected attributes and a technical quality score. Add an index to also get visually similar items from your own catalog in the same round trip.

curl -X POST https://api.visibilityzone.com/v1/analyze \
  -H "Authorization: Bearer $VZ_API_KEY" \
  -F file=@product.jpg \
  -F index=catalog_ss26 \
  -F top_k=5

{
  "type": "image",
  "labels": ["sneaker", "running", "mesh upper"],
  "attributes": { "category": "footwear", "pattern": "solid" },
  "colors": [{ "hex": "#1a2b3c", "ratio": 0.61 }],
  "quality": 0.94,
  "matches": [{ "id": "sku_8841", "score": 0.97 }],
  "latency_ms": 41
}

5. Sound analysis

Classifies audio, fingerprints it against your library, flags duplicates and returns the nearest acoustic matches. Useful for rights management, jingle and voice matching, and de-duplicating large sound libraries.

curl -X POST https://api.visibilityzone.com/v1/analyze \
  -H "Authorization: Bearer $VZ_API_KEY" \
  -F file=@jingle.mp3 \
  -F index=audio_library

{
  "type": "audio",
  "duration_s": 28.4,
  "classification": ["jingle", "upbeat"],
  "match": { "id": "track_2210", "confidence": 0.97 },
  "duplicates": 2,
  "latency_ms": 120
}

6. Text analysis

Returns intent, sentiment and entities, and — with an index — semantic matches that understand meaning rather than exact keywords. Synonyms, misspellings and morphological variants are handled without configuration.

curl -X POST https://api.visibilityzone.com/v1/analyze \
  -H "Authorization: Bearer $VZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"best wireless earbuds for running","index":"catalog_ss26"}'

{
  "type": "text",
  "intent": "purchase_research",
  "sentiment": "neutral",
  "entities": ["wireless earbuds", "running"],
  "matches": [{ "id": "sku_1207", "score": 0.95 }],
  "latency_ms": 22
}

7. Multimodal search

Send a file and text together and the query is interpreted as one intent: the image supplies the visual reference, the text supplies the modification. This is the same endpoint — you are not calling a different service.

curl -X POST https://api.visibilityzone.com/v1/analyze \
  -H "Authorization: Bearer $VZ_API_KEY" \
  -F file=@street-style.jpg \
  -F text="same jacket but in navy" \
  -F index=catalog_ss26

{
  "type": "multimodal",
  "matches": [
    { "id": "sku_1207", "score": 0.96, "color": "navy" }
  ],
  "latency_ms": 38
}

8. Indexing your catalog

Retrieval requires an index. You create one, push items to it, and reference it by name in any analyze call. Items can carry arbitrary metadata, which becomes available for filtering.

POST /v1/indexes            # create
POST /v1/indexes/:name/items # upsert items (batch up to 1,000)
GET  /v1/indexes/:name       # status and item count

# Upsert example
curl -X POST https://api.visibilityzone.com/v1/indexes/catalog_ss26/items \
  -H "Authorization: Bearer $VZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":"sku_8841","image_url":"https://…/1.jpg","metadata":{"color":"navy","in_stock":true}}]}'

Indexing is asynchronous. Items become searchable within seconds for small batches; large initial imports are processed in the background and report progress on the index status endpoint.

9. Response format

Every successful response is JSON and always contains type, request_id and latency_ms. Modality-specific fields are added on top of that base. Fields are additive across versions: we add keys, we do not silently remove or repurpose them.

10. Errors

Errors use conventional HTTP status codes and return a JSON body with a stable machine-readable code, a human-readable message and the request_id.

Retry 429, 500 and 503 with exponential backoff and jitter. Do not retry 4xx validation errors — they will fail identically.

11. Rate limits

Limits apply per API key and are returned on every response so you can adapt without guessing.

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785000000
Retry-After: 12          # only on 429

Default limits depend on your plan; see Pricing. Sustained higher throughput and burst allowances are configured per account — contact us before you launch a large migration so we can raise limits in advance.

12. Versioning and deprecation

The version is pinned in the URL path (/v1/). Within a major version we make only backward-compatible changes: new endpoints, new optional parameters and new response fields. Your integration will not break because we shipped a feature.

Breaking changes ship as a new major version. When a version is deprecated we announce it by email to account owners, mark it in these docs, and continue serving it for at least 12 months from the announcement. Security issues are the only exception, and we will contact affected customers directly.