1. Search
POST /api/v1/assets/search with a query. Needs a key with the search scope.
Loading...
Loading...
Search an AI image library from your own tool or agent, then fetch how each hit was made: prompt, seed and models. Two calls, one API key.
Search ranks assets and returns what you need to list them: id, title, tags, scores and thumbnails. It does not return the generation recipe. The recipe comes from a second call per asset.
POST /api/v1/assets/search with a query. Needs a key with the search scope.
GET /api/v1/assets/{asset_h} for each hit you care about. Needs a key with the read scope.
A tool that wants the recipe for its top five hits makes one search call and five detail calls.
In the app, open Settings, then Workspace, then API keys, and give the key the search and read scopes. The key starts with napi_ and is shown once.
export NUMONIC_API_KEY='napi_...'Send it as X-API-Key: napi_... or Authorization: Bearer napi_.... Never put the key in a URL. A key is bound to the workspace it was created in, so it can only ever search that workspace's assets.
Use orderBy relevance to rank by match. limit is 1 to 100 (default 20), and a text query pages with offset.
curl -sS -X POST https://www.numonic.ai/api/v1/assets/search \
-H "X-API-Key: $NUMONIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"neon alley at night, rain","orderBy":"relevance","limit":5}' \
| jq '.data[] | {asset_h, title, relevance_score}'Each result in data has asset_h, title, description, filename, mime_type, status, tags, a relevance score and a thumbnail URL. Search is limited to 120 requests per minute per key.
Search understands the image and its prompt. For video it works from one frame near the start, plus the metadata, so queries about motion or audio will not rank well.
Pass an asset_h from the search response.
curl -sS https://www.numonic.ai/api/v1/assets/<asset_h> \
-H "X-API-Key: $NUMONIC_API_KEY" \
| jq '{
title,
prompt: .prompts.positive,
seed: .generation_parameters.seed,
models: [.models[] | {type, name}]
}'A hit with full ComfyUI metadata returns something like this:
{
"title": "Neon alley v3",
"prompt": "neon alley, rain, cinematic",
"seed": 123456,
"models": [
{ "type": "checkpoint", "name": "flux1-dev.safetensors" },
{ "type": "lora", "name": "cinematic.safetensors" }
]
}prompts.positive holds the positive prompt and prompts.negative the negative one. For Midjourney assets the prompt is under midjourney_metadata.generation_details.
generation_parameters.seed, with model_name, steps, cfg_scale, sampler, scheduler, denoise, width and height alongside it.
models[] lists every model the generation used, in order: sequence, type (for example checkpoint or lora) and name.
provenance carries the creating prompt, the participating agents and the parent assets.
The recipe is only as complete as the metadata Numonic captured. An image with no embedded generation data has null prompts and generation_parameters and an empty models array. Handle null rather than assuming every hit has a seed.
Type the same text in the library search box and sort by relevance to see the same assets. Open an asset to see its prompt, seed and models in the detail view, which reads the same recipe the API returns.
Signed in? The same guide, written for the app, is in Help: Search API and Recipes.
Search it, fetch the recipe, and feed the result back to your agents.