Skip to content
© 2026 Velvari support@velvari.ee

Examples

A few fixed request snippets for common internal use. Keep this page short and use the reference page for the full contract.

How to use this page

These examples are fixed on purpose: they are meant to be copied, edited, and run quickly.
Replace placeholders: substitute your real API key and sample values before using them.
Keep Reference nearby: /reference remains the full parameter and response guide.

Public meta

Use these unauthenticated endpoints for liveness checks and raw contract delivery. 

curl "https://api.velvari.ee/healthz"
curl "https://api.velvari.ee/openapi.yaml"
Use it for: deployment health checks, runtime smoke tests, and tooling that needs the current OpenAPI YAML.
Reference: Meta endpoints

Taxi cards v2

Use the strict v2 taxi-card contract for new integrations. Search accepts one primary lookup field at a time: q, id, number, registration_mark, or vin. 

curl "https://api.velvari.ee/v2/cards/taxi?registration_mark=123ABC&include_vehicle=true" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v2/cards/taxi/mtr%3Ataxi-card%3Anumber%3ATVSK037464?include_raw=true" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v2/cards/taxi?number=TVSK037464" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
Use it for: registration-mark, holder-name, card-number, card-id, and VIN lookups against the preferred taxi-card API.
Status filter: use valid; old kehtiv and validity_status names are documented as compatibility aliases.
Auth: send either X-API-Key or Authorization: Bearer with the same server-issued API key.
Reference: Taxi Cards v2

ORS route summary

Use this normalized helper when you need distance, duration, and map-ready geometry for two coordinates. 

curl "https://api.velvari.ee/v1/ors/route?start_lng=24.7536&start_lat=59.437&end_lng=24.7736&end_lat=59.427" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v1/ors/autocomplete?text=Narva%20mnt&size=5&country=EST&layers=venue,address" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v1/ors/reverse?lat=59.3579&lng=27.4129" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v1/ors/isochrones?lng=24.7536&lat=59.437&range=300,600&profile=driving-car" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
Use it for: compact route summaries, address suggestions, reverse geocoding, and reachable-area checks through the OpenRouteService integration.
Reference: OpenRouteService endpoints

Suno cached songs

Use these endpoints to read, search, summarize, or refresh the enriched cached song snapshot for an allowed public Suno profile. The cached song items can include public feed metadata such as media URLs, workflow type/task, remix and instrumental flags, model fields, style prompts, lyrics, duration, counters, and sync diagnostics when Suno exposes them anonymously. 

curl "https://api.velvari.ee/v1/suno/profiles/akaki/songs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v1/suno/songs/search?artist=akaki&title=Night%20Ride" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v1/suno/profiles/akaki/songs/search?style=electro-pop&min_play_count=10&sort=-play_count&limit=10" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v1/suno/songs/132ec409-86b3-4587-87f8-a32ae30446d3" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v1/suno/profiles/akaki/stats" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
curl "https://api.velvari.ee/v1/suno/profiles/akaki/sync" \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json"
Use it for: checking the current local snapshot, finding songs by title or profile filters, looking up a song by UUID, reading aggregate counters, or refreshing through anonymous public profile and unified-feed pagination.
Search mode: /v1/suno/songs/search matches a title for an allowed artist handle, while /v1/suno/profiles/{handle}/songs/search filters one cached profile by title, style, lyrics, model, minimum play count, sort, and limit.
Handle allow-list: the path handle must be enabled by SUNO_ALLOWED_HANDLES; global song lookup scans allowed cached snapshots only.
Auth model: no private Suno account token, Browser-Token, Device-Id, cookies, or login flow is required.
Sync safety: refreshes are bounded by configured page and timeout limits, deduplicate songs by ID, and avoid overwriting a larger existing snapshot with a warning-state partial result.
Reference: Suno endpoints

ORS directions proxy

Use this thin proxy when you need an authenticated POST request with a JSON body and the upstream ORS response shape. 

curl "https://api.velvari.ee/v1/ors/directions/driving-car" \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"coordinates":[[24.7536,59.437],[24.7736,59.427]]}'
curl "https://api.velvari.ee/v1/ors/matrix/driving-car" \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{"locations":[[24.7536,59.437],[24.7736,59.427]],"metrics":["duration","distance"]}'
Use it for: directions and matrix calls through the OpenRouteService proxy. Successful upstream payloads pass through as JSON.
Reference: OpenRouteService endpoints

Next

Reference

Full parameter, request-body, response, auth, and endpoint details.

OpenAPI

Raw spec access and the snapshot workflow behind these docs.