Cards
Data for typed cards: weather, places, geocoding, static maps, exchange rates and link previews as ready card blocks.
Every JSON endpoint returns { block, provenance }, where block is a valid @codai/cards block. Places, geocoding and static maps are billed at Google list price and limited per user per day (200 Places, 500 maps, 500 link previews, 2000 renders; super_admin exempt). POST /v1/cards/render turns a chart or qr block into a PNG or SVG; Mermaid and math blocks are not supported yet (422 render_unsupported). Schema, agent tools and billing: cards guide.
bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
lat*number-90 <= value <= 90lng*number-180 <= value <= 180name?stringDisplay name of the location shown on the card.
length <= 200x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128A weather block and its provenance.
application/json- response
A ready-to-render card block from @codai/cards plus where its data came from.
block*A card block (weather, places, map, metric, table or links); null when nothing matched.
results?array<>Geocode only — the raw matches behind the map block.
route?Route only — { mode, durationS, staticDurationS, distanceM, polyline }, null when no route was found.
result?Track only — the carrier, AWB, whether live tracking is configured, events and the tracking link.
documents?array<>e-Factura only — the caller's fiscal documents with their ANAF e-Factura status.
provenance*Source, attribution, fetch time, whether it came from cache and (for paid calls) the charged cost.
curl -X GET 'https://ai.codai.ro/v1/cards/weather?lat=-90&lng=-180'{ "block": {}, "results": [ {} ], "route": {}, "result": {}, "documents": [ {} ], "provenance": {}}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
q?stringlength <= 300lat?number-90 <= value <= 90lng?number-180 <= value <= 180radius?integer50 <= value <= 500002000type?stringNearby only — up to 5 comma-separated Google place types, e.g. restaurant,cafe.
limit?integer1 <= value <= 208lang?string"ro"region?stringopen_now?string"1""0""true""false"x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128A places block (null when nothing matched) and its provenance, including the charged cost.
application/json- response
A ready-to-render card block from @codai/cards plus where its data came from.
block*A card block (weather, places, map, metric, table or links); null when nothing matched.
results?array<>Geocode only — the raw matches behind the map block.
route?Route only — { mode, durationS, staticDurationS, distanceM, polyline }, null when no route was found.
result?Track only — the carrier, AWB, whether live tracking is configured, events and the tracking link.
documents?array<>e-Factura only — the caller's fiscal documents with their ANAF e-Factura status.
provenance*Source, attribution, fetch time, whether it came from cache and (for paid calls) the charged cost.
curl -X GET 'https://ai.codai.ro/v1/cards/places'{ "block": {}, "results": [ {} ], "route": {}, "result": {}, "documents": [ {} ], "provenance": {}}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
address*string2 <= length <= 300lang?string"ro"region?stringx-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128A map block (null when the address was not found), the results and provenance.
application/json- response
A ready-to-render card block from @codai/cards plus where its data came from.
block*A card block (weather, places, map, metric, table or links); null when nothing matched.
results?array<>Geocode only — the raw matches behind the map block.
route?Route only — { mode, durationS, staticDurationS, distanceM, polyline }, null when no route was found.
result?Track only — the carrier, AWB, whether live tracking is configured, events and the tracking link.
documents?array<>e-Factura only — the caller's fiscal documents with their ANAF e-Factura status.
provenance*Source, attribution, fetch time, whether it came from cache and (for paid calls) the charged cost.
curl -X GET 'https://ai.codai.ro/v1/cards/geocode?address=string'{ "block": {}, "results": [ {} ], "route": {}, "result": {}, "documents": [ {} ], "provenance": {}}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
center?stringzoom?integer1 <= value <= 20w?integer64 <= value <= 640640h?integer64 <= value <= 400400markers?stringmaptype?string"roadmap""roadmap""satellite""terrain""hybrid"lang?string"ro"path?stringx-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128The map image.
response?fileimage/pngbinarycurl -X GET 'https://ai.codai.ro/v1/cards/static-map'"string"bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
source?string"bnr""bnr""ecb"from?stringto?stringamount?number1quote?stringsymbols?stringx-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128A metric or table block and its provenance (publication date).
application/json- response
A ready-to-render card block from @codai/cards plus where its data came from.
block*A card block (weather, places, map, metric, table or links); null when nothing matched.
results?array<>Geocode only — the raw matches behind the map block.
route?Route only — { mode, durationS, staticDurationS, distanceM, polyline }, null when no route was found.
result?Track only — the carrier, AWB, whether live tracking is configured, events and the tracking link.
documents?array<>e-Factura only — the caller's fiscal documents with their ANAF e-Factura status.
provenance*Source, attribution, fetch time, whether it came from cache and (for paid calls) the charged cost.
curl -X GET 'https://ai.codai.ro/v1/cards/fx'{ "block": {}, "results": [ {} ], "route": {}, "result": {}, "documents": [ {} ], "provenance": {}}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
origin?stringfrom?string2 <= length <= 300destination?stringto?string2 <= length <= 300mode?string"drive""drive""walk""bicycle""transit""two_wheeler"depart_at?stringdate-timelang?string"ro"region?stringx-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128A map block, the route summary (both null when no route) and provenance.
application/json- response
A ready-to-render card block from @codai/cards plus where its data came from.
block*A card block (weather, places, map, metric, table or links); null when nothing matched.
results?array<>Geocode only — the raw matches behind the map block.
route?Route only — { mode, durationS, staticDurationS, distanceM, polyline }, null when no route was found.
result?Track only — the carrier, AWB, whether live tracking is configured, events and the tracking link.
documents?array<>e-Factura only — the caller's fiscal documents with their ANAF e-Factura status.
provenance*Source, attribution, fetch time, whether it came from cache and (for paid calls) the charged cost.
curl -X GET 'https://ai.codai.ro/v1/cards/route'{ "block": {}, "results": [ {} ], "route": {}, "result": {}, "documents": [ {} ], "provenance": {}}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
awb*string^[A-Za-z0-9 ]{6,40}$carrier?string"sameday""fan""cargus""dpd"x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128A timeline block (null when there are no events), the tracking result and provenance (tracking link).
application/json- response
A ready-to-render card block from @codai/cards plus where its data came from.
block*A card block (weather, places, map, metric, table or links); null when nothing matched.
results?array<>Geocode only — the raw matches behind the map block.
route?Route only — { mode, durationS, staticDurationS, distanceM, polyline }, null when no route was found.
result?Track only — the carrier, AWB, whether live tracking is configured, events and the tracking link.
documents?array<>e-Factura only — the caller's fiscal documents with their ANAF e-Factura status.
provenance*Source, attribution, fetch time, whether it came from cache and (for paid calls) the charged cost.
curl -X GET 'https://ai.codai.ro/v1/cards/track?awb=string'{ "block": {}, "results": [ {} ], "route": {}, "result": {}, "documents": [ {} ], "provenance": {}}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
limit?integer1 <= value <= 5010x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128A table block (null when there are no documents), the documents and provenance.
application/json- response
A ready-to-render card block from @codai/cards plus where its data came from.
block*A card block (weather, places, map, metric, table or links); null when nothing matched.
results?array<>Geocode only — the raw matches behind the map block.
route?Route only — { mode, durationS, staticDurationS, distanceM, polyline }, null when no route was found.
result?Track only — the carrier, AWB, whether live tracking is configured, events and the tracking link.
documents?array<>e-Factura only — the caller's fiscal documents with their ANAF e-Factura status.
provenance*Source, attribution, fetch time, whether it came from cache and (for paid calls) the charged cost.
curl -X GET 'https://ai.codai.ro/v1/cards/efactura'{ "block": {}, "results": [ {} ], "route": {}, "result": {}, "documents": [ {} ], "provenance": {}}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128application/json- body
url*stringlength <= 2048A links block with one preview item and its provenance.
application/json- response
A ready-to-render card block from @codai/cards plus where its data came from.
block*A card block (weather, places, map, metric, table or links); null when nothing matched.
results?array<>Geocode only — the raw matches behind the map block.
route?Route only — { mode, durationS, staticDurationS, distanceM, polyline }, null when no route was found.
result?Track only — the carrier, AWB, whether live tracking is configured, events and the tracking link.
documents?array<>e-Factura only — the caller's fiscal documents with their ANAF e-Factura status.
provenance*Source, attribution, fetch time, whether it came from cache and (for paid calls) the charged cost.
curl -X POST 'https://ai.codai.ro/v1/cards/unfurl' \ -H 'Content-Type: application/json' \ -d '{ "url": "string"}'{ "block": {}, "results": [ {} ], "route": {}, "result": {}, "documents": [ {} ], "provenance": {}}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128application/json- body
url*stringlength <= 2048lang?stringLanguage of the availability badge (for example "Out of stock" / "Stoc epuizat").
"en""en""ro"A products block with one item and its provenance (source page).
application/json- response
A ready-to-render card block from @codai/cards plus where its data came from.
block*A card block (weather, places, map, metric, table or links); null when nothing matched.
results?array<>Geocode only — the raw matches behind the map block.
route?Route only — { mode, durationS, staticDurationS, distanceM, polyline }, null when no route was found.
result?Track only — the carrier, AWB, whether live tracking is configured, events and the tracking link.
documents?array<>e-Factura only — the caller's fiscal documents with their ANAF e-Factura status.
provenance*Source, attribution, fetch time, whether it came from cache and (for paid calls) the charged cost.
curl -X POST 'https://ai.codai.ro/v1/cards/product' \ -H 'Content-Type: application/json' \ -d '{ "url": "string"}'{ "block": {}, "results": [ {} ], "route": {}, "result": {}, "documents": [ {} ], "provenance": {}}bearerAuthAuthorizationBearer <codai_…>A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).
x-request-id?stringClient correlation id; echoed back as x-codai-trace-id and persisted on the usage row.
length <= 128application/json- body
block*A chart or qr card block.
format?string"png""png""svg"width?integer64 <= value <= 1200480height?integer64 <= value <= 1200300theme?string"light""light""dark"scale?integer1 <= value <= 32The image. x-codai-render-size carries the output size in pixels (WIDTHxHEIGHT).
response?filebinarycurl -X POST 'https://ai.codai.ro/v1/cards/render' \ -H 'Content-Type: application/json' \ -d '{ "block": { "type": "string" }}'"string"