canonical: https://jentic.com/apis/numonic.ai/numonic

# Numonic API

The Numonic API stores, searches, and organizes creative assets such as images, video, audio, and 3D models, and records where each one came from. Assets can be created from a storage path, imported from ComfyUI, tagged in bulk, grouped into nested collections, and published as public galleries with a metadata disclosure preset. Search runs in modes from exact and fuzzy to full-text and semantic vector search, with facets and autocomplete suggestions. Provenance features return an asset's lineage, cross-tool lineage, Midjourney evolution chain, and EXIF metadata, and generate C2PA manifests, alongside webhooks, automation rules, pipelines, prompt libraries, and a production review queue.

## For AI agents

Search and organize creative assets in Numonic, group them into collections and publish galleries, trace AI-generation lineage and C2PA provenance, and run review, webhook, and automation workflows.

## Scope

Does not generate images or video, transcode media, or deliver assets through a CDN. Use for storing, searching, organizing, publishing, and tracing the provenance of creative assets only.

## Capabilities

- Search creative assets in exact, fuzzy, fulltext, boolean, or smart mode, or by semantic vector similarity
- Group assets into nested collections and publish a collection as a public gallery with a share, portfolio, client, or archive preset
- Trace an asset's lineage, cross-tool lineage, and Midjourney evolution chain, and read its EXIF technical metadata
- Generate and read C2PA provenance manifests for an asset
- Import ComfyUI files and parse the ComfyUI workflow embedded in an asset
- Bulk tag, soft-delete, restore, and export assets by their hashes
- Register webhooks for events such as asset.created and submit assets to a production review queue

## Use cases

### Creative asset librarian agent

A design team's AI agent answers requests like 'find the hero images from the spring shoot' without anyone browsing folders. Through Jentic the agent searches for 'search creative assets', gets the Numonic search operation with its input schema, and sends a query with mode set to smart or fulltext plus filters. For look-alike requests it calls the semantic search operation instead, and the x-api-key is attached at call time.

Example prompt: Call POST `/api/v1/assets/search` with query 'spring shoot hero', mode smart, and limit 20, then call POST `/api/v1/assets/thumbnail-urls` with the returned assetIds and present the thumbnails

### Client gallery publishing

An agency shares selected work with a client without exposing internal metadata. It creates a collection, adds assets to it by assetH, and publishes it as a public gallery with the client preset, which keeps disclosed metadata minimal. GET `/api/v1/collections/{collectionH}/publication` reports the publication status, and unpublishing is a single DELETE.

Example prompt: Call POST `/api/v1/collections` with name 'acme-review', add each asset with POST `/api/v1/collections/{collectionH}/assets` using its assetH, then call POST `/api/v1/collections/{collectionH}/publish` with privacyPreset client

### AI-generation provenance and C2PA

Teams publishing AI-generated work need to show how it was made. Numonic returns an asset's lineage and cross-tool lineage, the Midjourney evolution chain, and the ComfyUI workflow metadata, and it can generate a C2PA manifest for the asset. That gives reviewers and downstream platforms a verifiable record of the source and edits.

Example prompt: Call GET `/api/v1/assets/{assetH}/lineage` and GET `/api/v1/assets/{assetH}/workflow-metadata` for an asset, then call POST `/api/v1/assets/{assetH}/c2pa` to generate its manifest and GET `/api/v1/assets/{assetH}/c2pa` to read it back

### Review queue and event-driven automation

A studio routes finished assets through approval and reacts to library changes. Assets go into the production review queue with POST `/api/v1/production-review/submissions`, where reviewers add comments and record decisions. Webhooks registered for events such as asset.created and asset.updated notify other systems, and the HMAC signing secret can be rotated on demand.

Example prompt: Call POST `/api/v1/webhooks` with name 'library-sync', url https://example.com/hooks/numonic, and events asset.created and asset.updated, then call POST `/api/v1/webhooks/{id}/test` to send a test event

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/assets/search` | Search assets |
| POST | `/api/v1/assets/search-semantic` | Semantic vector search |
| GET | `/api/v1/assets/{assetH}` | Get asset details |
| POST | `/api/v1/collections` | Create a collection |
| POST | `/api/v1/collections/{collectionH}/publish` | Publish a collection |
| GET | `/api/v1/assets/{assetH}/lineage` | Get asset lineage |
| POST | `/api/v1/assets/{assetH}/c2pa` | Generate C2PA manifest |
| POST | `/api/v1/webhooks` | Register a webhook |

## Key resources

- **Assets** — Creative files with metadata, tags, notes, lineage, C2PA manifests, technical and workflow metadata
- **Collections** — Nested groups of assets that can be published as public galleries
- **Webhooks, rules, and pipelines** — Event subscriptions, automation rules with trigger configs, and saved or ad-hoc pipelines
- **Prompts and models** — A versioned prompt library and the generation models linked to assets
- **Production review** — Review submissions with comments and recorded decisions

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 47 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 92 / 100
  - Developer Experience & Jentic Compatibility: 62 / 100
  - AI-Readiness & Agent Experience: 24 / 100
  - Agent Usability: 78 / 100
  - Security: 50 / 100
  - AI Discoverability: 72 / 100
- **View full report:** https://jentic.com/apis/numonic.ai/numonic/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Numonic by hand means sending the napi_ key in x-api-key, passing X-Tenant-ID on multi-tenant keys, addressing assets and collections by 40-character hashes, and picking the right search variant. Through Jentic you install once, import Numonic from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Numonic puts the collection hash in the URL path (`/api/v1/collections/{collectionH}/...`), so a rule can pin your agent to one collection and the operations you pick. You choose the operations it may call, so destructive ones like bulk-delete or webhook deletion are not included unless you add them.
- **Credential handling:** Your Numonic API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search creative assets' or 'generate a C2PA manifest', and Jentic returns the matching Numonic operation with its input schema, so the agent picks the right one of the asset, collection, and provenance operations without browsing the reference docs.

## Related APIs

- **Brandfolder API** — Brand asset management for marketing teams
- **Cloudinary Admin API** — Media library management with tagging and search
- **Stability AI API** — Image generation and editing models
- **Replicate API** — Run hosted generative models through one API

## FAQ

### What authentication does the Numonic API use?

Per its OpenAPI spec, the Numonic API authenticates with an API key prefixed napi_, sent in the x-api-key header and generated in the Numonic dashboard under Settings, API Keys. A key with access to several tenants can pass X-Tenant-ID to pick one. The health checks and the public gallery endpoints are open and need no key. Through Jentic the key is held by your own instance and injected at call time.

### Can I search Numonic assets by visual similarity?

Yes. POST `/api/v1/assets/search-semantic` runs semantic vector search from a required query, and POST `/api/v1/assets/search` accepts a similarToAssetH or queryVector alongside its other options. The standard search also supports exact, partial, fuzzy, fulltext, boolean, and smart modes, with facets from POST `/api/v1/assets/facets.`

### What are the rate limits for the Numonic API?

The OpenAPI spec does not state numeric request limits for the API. Check the Numonic API documentation at https://numonic.ai/docs/api for current limits.

### Does the Numonic API support C2PA content credentials?

Yes. POST `/api/v1/assets/{assetH}/c2pa` generates a C2PA manifest for an asset and GET `/api/v1/assets/{assetH}/c2pa` returns it. You can also record a provenance assertion with POST `/api/v1/assets/{assetH}/provenance` and read lineage for the same asset.

### How do I publish a collection as a gallery through Jentic?

Search Jentic for 'publish a collection as a gallery', load the Numonic publish operation, and call POST `/api/v1/collections/{collectionH}/publish` with a privacyPreset such as client or portfolio. Check the result with GET `/api/v1/collections/{collectionH}/publication.` To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a Numonic MCP server?

You do not need an MCP server to give your agent Numonic. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent discovers the asset, collection, and provenance operations it needs on demand.

### Can I limit what my agent is allowed to do with the Numonic API?

Yes. For a search assistant, write a rule that allows POST `/api/v1/assets/search`, POST `/api/v1/assets/search-semantic`, and GET `/api/v1/assets/{assetH}`, so it can find and inspect assets but cannot run bulk deletes, publish galleries, or change webhooks. The calls it makes are logged for review.