Numonic

Durchsuchen, organisieren und veröffentlichen Sie KI-generierte Bilder und Videos mit Herkunft und Abstammung.

Gehosteter MCP-Server

npx add-mcp 'https://www.numonic.ai/mcp'

Installiert in Claude Code, Codex, Cursor und mehr

Dokumentation

▸Tools (72) ▸Resources (5)

Collection Tree
Storage Usage
Export Presets
Pipeline Templates
Asset Details ▸Prompts (5)
Search & Curate
Ingest & Organize
Export for Client
Audit Tenant Health
Explore Lineage ▸Protocol
Error Codes
Protocol Details
Further Reading

MCP Server Reference

Connect AI agents to your digital asset library via Model Context Protocol. 72 tools across 13 domains, 5 resources, and 5 guided prompts — ready for Claude, ChatGPT, Gemini, Codex, VS Code, Cursor, and custom agents built on the MCP SDKs. Every MCP tool has a REST equivalent in the REST API Reference.

Tools

Resources

Prompts

Transport

HTTP / JSON-RPC 2.0

Endpoint: POST https://www.numonic.ai/mcp

Connect an agent

Give ChatGPT, Claude, Cursor, Codex and other MCP-compatible agents access to your Numonic assets, collections and workflows. There are two ways to authenticate, and both use the same endpoint:

https://www.numonic.ai/mcp

New to Numonic MCP? Follow the connect-an-agent quickstart. It helps you choose an authentication method, connect your AI client, and check that it works.

Already connected? Jump to client-specific configuration, the tool reference, or how authentication works.

Client Configuration

Most chat assistants connect through OAuth. Many developer tools support API keys, and some also support OAuth. Choose your client below for the methods it supports. Every client uses the same endpoint:

https://www.numonic.ai/mcp

Step-by-step setup and config snippets for each client live in the connect-an-agent quickstart. Each link opens that client’s instructions, or jump straight to the tool reference.

Authentication

Which credential to use

Client	Credential	Notes
Connector apps: Claude, ChatGPT, Gemini, Grok, Le Chat, Perplexity, Copilot Studio	OAuth 2.1 (authorization code + PKCE)	The client discovers the authorization server from the endpoint, registers itself, and sends you to a Numonic consent page. You choose the workspace and permissions there. No key to paste.
Claude Code, Codex, Gemini CLI, VS Code, Cursor, Devin Desktop, scripts and custom agents	API key (napi_...) in a header	Create the key under Settings → Workspace → Connected Agents and send it as shown for your client in the quickstart.
Anything using a Numonic or Supabase login session token	Not accepted	A session or access token from signing in to Numonic is rejected with 401. Use an API key, or connect through OAuth.

OAuth connection permissions

On the consent page you grant a connection some of the following Numonic permissions. They are separate from the OAuth scopes the client requests (identity only, such as openid). A connection acts as its own agent, not as you, and you can disconnect it at any time under Settings → Workspace → OAuth connectors. Reconnecting a connector replaces its earlier connection.

read	View assets, collections and their details
search	Search your library
write	Add and update assets, tags and collections, and remove tags and annotations. Warning: this changes your library, and an agent with write can edit or remove what is already there.
export	Export and publish assets. Warning: this sends content out of Numonic; published collections and exports can be opened by people outside your workspace.

admin (running pipelines, registering webhooks) cannot be granted to an OAuth connection. It can only be held by an API key. A key with admin can call every tool, including those that need search, write or export, but the create-key screen still lists each permission separately (read is always ticked), so tick what the key should show. Use a dedicated key for admin rather than the one your everyday agent uses.

API keys

All API keys must start with the napi_ prefix. Keys are SHA-256 hashed server-side — Numonic never stores your raw key.

Method	Header	Note
Bearer token	Authorization: Bearer napi_...	Required by most MCP clients
API key header	X-API-Key: napi_...	Preferred for direct HTTP
Legacy header	api-key: napi_...	Backwards compatibility

Multi-tenant access

If your API key has access to multiple tenants, pass X-Tenant-ID to select which tenant to operate on. If omitted, the key's default tenant is used.

Tools(72)

Atomic operations your agent can call via tools/call. Each tool accepts a JSON arguments object and returns structured results. Also see 5 resources and 5 prompts.

All categories
Search and discover 3
Ingest and update 3
Provenance and lineage 1
Collections and curation 7
Annotations 4
Models and versions 6
Prompts 4
Experiments and evaluations 5
Pipelines 11
Automation and webhooks 4
Publishing and export 9
Analytics and administration 2
Prospects and relationships 13

Ingest and update3 tools

Store assets and edit their metadata and tags.

Bulk Update Asset Tags

BulkUpdateAssetTags

Add or remove tags across up to 100 assets at once.

Ingest and update Can write Permission: write OAuth or API key

Add or remove a set of tags across up to 100 assets in one call. Per-asset behaviour: 'add' merges into the existing tag set (deduped); 'remove' deletes the listed tags from each asset. Assets whose tag set does not change are skipped silently and reported as unchanged in the response. Tenant-scoped; uses the same RLS path as PATCH /api/v1/assets/bulk-tag.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
asset_hs	string[]	required	Array of asset hashes (SHA-1, 40-char hex) to apply the operation to. Min 1, max 100.
operation	string	required	'add' merges the tags into each asset's existing tag set (deduped); 'remove' deletes them. For replace-all semantics on a single asset, use UpdateAsset. enum: `add · remove`
tags	string[]	required	Tag strings to add or remove. Min 1 char, max 100 chars per tag. Min 1 tag, max 50 tags per call.

Related: UpdateAsset

Store Asset

StoreAsset

Upload a file with metadata; lineage is extracted server-side.

Ingest and update Can write Permission: write OAuth or API key

Store an asset (file) in Numonic with metadata and lineage. Provide EXACTLY ONE of: base64 bytes (asset_data_base64), a reference to a pre-uploaded object (asset_storage_ref), or an HTTPS URL the Edge Function will fetch server-side (asset_data_url). The URL channel accepts allowlisted hosts only (built-in list, plus any extra hosts a deployment adds via MCP_URL_INGEST_ALLOWLIST; built-in: signed Supabase/Numonic storage URLs, Comfy Cloud, Midjourney CDN, Civitai, S3 virtual-hosted buckets, fal output URLs (fal.media, v3.fal.media, v3b.fal.media) and Replicate output URLs (*.replicate.delivery)). For a fal or Replicate generation, pass the output URL straight to asset_data_url, and do it promptly: Replicate URLs expire after an hour (URL_EXPIRED). OpenAI and Google image APIs return bytes, not URLs. For those, or any file over ~3 MB, an agent with a shell should upload the bytes itself instead of sending base64 (the /mcp request body is capped at 4.5 MB). The steps: (1) GET https://www.numonic.ai/api/v1/storage/signed-url/upload?filename=<name>&contentType=<mime> with headers Authorization: Bearer <napi_ key with write scope> and X-Tenant-ID: <tenant_id>; (2) PUT the file bytes to the returned signedUrl with Content-Type: <mime>; (3) call StoreAsset with asset_storage_ref.storagePath = the returned path (it must start with your tenant_id) plus prompt_metadata. Alternatively, step (3) can be POST /api/v1/assets {storagePath, filename, mimeType}, which records the upload but carries no prompt. Default size cap 100 MB (MCP_URL_INGEST_MAX_BYTES); default fetch timeout 30s (override per-call via timeout_seconds, max 300). Distinct error codes: URL_EXPIRED, URL_FORBIDDEN_HOST, URL_TOO_LARGE, URL_FETCH_TIMEOUT, URL_CONTENT_TYPE_MISMATCH. Lineage is determined by the server: after upload Numonic extracts the prompt, workflow and models embedded in the file (e.g. ComfyUI PNG/MP4 metadata) and GetAssetDetails reports them with provenance.lineage_source. prompt_metadata is OPTIONAL — omit it when you do not know how the asset was made (never invent a prompt or agent hash); an asserted empty or "none" value never overrides what extraction finds. IMPORTANT for chat-attached files: developer-mode MCP connectors do not reliably receive a file reference for a file attached directly in chat (OpenAI Apps SDK openai/fileParams hydration is documented for first-party Apps SDK directory apps and is unconfirmed for custom developer-mode connectors — see GitLab #2807). If the user attaches an image/file in chat and asks you to store it, do NOT re-encode a large attachment as asset_data_base64 yourself — a large inline re-encode can run for minutes and get cancelled. Ask the user for a URL to pass via asset_data_url instead, or use asset_storage_ref if the file was already uploaded to a Numonic-issued signed URL.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Tenant ID (optional — auto-injected from API key auth, omit for automatic tenant detection)
filename	string	required	Original filename (non-empty)
mime_type	string	required	MIME type of the asset (e.g., 'image/png', 'text/plain')
asset_data_base64	string	optional	Base64-encoded asset bytes for small assets. Provide either this OR asset_storage_ref.
poster_image_base64	string	optional	Optional, 3D only (mime_type model/*): a base64 PNG, JPEG or WebP preview of the model. Numonic cannot render 3D server-side, so without it the asset shows a placeholder until someone opens the gallery in a browser. With it, the asset gets a thumbnail and is enriched for search right away. Rejected for non-3D assets.
poster_mime_type	string	optional	MIME type of poster_image_base64. Defaults to image/png. enum: `image/png · image/jpeg · image/webp`
asset_data_url	string ·uri	optional	HTTPS URL the Edge Function will fetch server-side. Allowlisted hosts only. Mutually exclusive with asset_data_base64 / asset_storage_ref. Returns dedicated error codes (URL_EXPIRED / URL_FORBIDDEN_HOST / URL_TOO_LARGE / URL_FETCH_TIMEOUT / URL_CONTENT_TYPE_MISMATCH).
allow_content_type_mismatch	boolean	optional	When asset_data_url is used, accept responses whose Content-Type does not match mime_type. Defaults to true because Comfy Cloud serves PNGs as application/octet-stream.
timeout_seconds	integer	optional	Per-call fetch timeout for asset_data_url (5–300s). Default 30.
asset_storage_ref	object	optional	Reference to asset data already uploaded via signed URL. Mutually exclusive with asset_data_base64 / asset_data_url.
prompt_metadata	object	optional	OPTIONAL client assertion of how this asset was generated (prompt + responding agent). Omit it if you do not know; the server extracts lineage from the stored file and extracted data always wins over an empty or "none" assertion.
asset_metadata	object	optional	Optional descriptive metadata for the asset.
tags	string[]	optional	Optional array of tag names to apply to the asset.
collection_h	string	optional	Optional Collection Hash (SHA-1) to add this asset to immediately on creation.
parent_asset_h	string	optional	Optional Asset Hash (SHA-1) of a parent asset if this is a version or derivation.

Related: GetAssetDetails, UpdateAsset

Update Asset

UpdateAsset

Edit one asset's title, description, tags or status (approve or clear approval).

Ingest and update Can write Permission: write OAuth or API key

Partial update of a single asset's metadata: description, title, tags, and/or status. Tag update on this tool REPLACES the entire existing tag set; for incremental add/remove operations across multiple assets use BulkUpdateAssetTags. Set status to Approved to mark an approved brand asset (find them later with SearchAssets filters.status='Approved' or the query 'status:Approved'); set Draft, PendingApproval, Rejected or Archived to clear approval. At least one of description, title, tags or status must be provided. Tenant-scoped; calls the same update_asset_metadata function as PATCH /api/v1/assets/[assetH].

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
asset_h	string	required	Asset hash (SHA-1, 40-char hex) of the asset to update.
description	string	optional	Optional new asset description (max 5000 chars). Replaces any existing description verbatim.
title	string	optional	Optional new asset title (max 500 chars).
tags	string[]	optional	Optional new tag set. REPLACES the entire existing tag set. For incremental add/remove use BulkUpdateAssetTags. Min 0 tags, max 500. Each tag 1–100 chars.
status	string	optional	Optional new asset status. Approved marks an approved brand asset; any other value clears approval. enum: `Draft · PendingApproval · Approved · Rejected · Archived`

Provenance and lineage1 tool

Trace how an asset was made: parents, evolution chains, models used.

Get Midjourney Evolution Chain

GetMidjourneyEvolutionChain

Parent-to-child evolution chain of a Midjourney asset.

Provenance and lineage Read-only Permission: read OAuth or API key

Retrieve the evolution chain (parent→child lineage) for a Midjourney asset, showing how it evolved through variations and upscales. Steps that are another member's private generations appear as placeholder nodes (redacted: true, job_type "private", no asset, prompt or command); describe them as private steps rather than inferring their content.

Parameter	Type	Required	Description
asset_id	string	required	The Asset Hash (SHA-1) of the asset to get evolution chain for
max_depth	number	optional	Maximum depth to traverse (default: 10, max: 50)

Annotations4 tools

Attach, revise and remove audited notes on workflow nodes.

Create Annotation

CreateAnnotation

Add an audited annotation to a workflow node.

Annotations Can write Permission: write OAuth or API key

Create a new annotation on a ComfyUI workflow node with full audit trail.

Parameter	Type	Required	Description
workflow_node_id	string	required	40-character hexadecimal workflow node identifier
content	string	required	Annotation text content (1-10000 characters)
content_type	string	optional	Content format type enum: `text · markdown · json`
visibility	string	optional	Visibility level: private (author only), team (tenant), public (all) enum: `private · team · public`

Delete Annotation

DeleteAnnotation

Soft-delete an annotation, keeping the audit trail.

Annotations Can write Permission: write OAuth or API key

Delete (soft delete) an annotation - marks it as deleted without removing data.

Parameter	Type	Required	Description
annotation_id	string	required	40-character hexadecimal annotation identifier

Related: GetAnnotations

Get Annotations

GetAnnotations

List annotations on a workflow node.

Annotations Read-only Permission: read OAuth or API key

Retrieve all annotations for a specific ComfyUI workflow node with author information.

Parameter	Type	Required	Description
workflow_node_id	string	required	40-character hexadecimal workflow node identifier
include_resolved	boolean	optional	Include resolved annotations in results (default: false)

Related: CreateAnnotation

Update Annotation

UpdateAnnotation

Revise an annotation as a new superseding version.

Annotations Can write Permission: write OAuth or API key

Update an existing annotation by creating a new version via supersession chain (effectivity pattern).

Parameter	Type	Required	Description
annotation_id	string	required	40-character hexadecimal annotation identifier
content	string	optional	Updated annotation content (optional)
visibility	string	optional	Updated visibility level (optional) enum: `private · team · public`

Models and versions6 tools

Browse the Model Library, link models to assets, track versions.

Add Model Version

AddModelVersion

Record a new model version with training metadata.

Models and versions Can write Permission: write OAuth or API key

Add a version to a model with training metadata, quality score, and recommended flag.

Parameter	Type	Required	Description
model_hash	string	required	SHA-1 hash key of the model
version_tag	string	required	Version label (e.g., v1.0, v2.0, epoch10)
version_notes	string	optional	Changelog or description for this version
training_steps	integer	optional	Total training steps
training_epochs	integer	optional	Total training epochs
training_config	object	optional	Training hyperparameters: {"lr": 0.0001, "optimizer": "AdamW"}
quality_score	number	optional	Quality rating (0-10)
is_recommended	boolean	optional	Mark as the recommended version for this model
trained_at	string ·date-time	optional	When this version was trained

REST equivalent: none (MCP only)

Related: GetModelVersions

Get Asset Models

GetAssetModels

Models used to generate a given asset.

Models and versions Read-only Permission: read OAuth or API key

Get the Model Library records for every model used to generate a specific asset (checkpoints, UNETs, LoRAs with weights, VAEs, CLIP, upscalers), with base model, type and detection source. Scoped to your tenant: an asset your tenant does not hold returns no models. For the prompt and ComfyUI workflow graph, call GetAssetDetails.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
asset_hash	string	required	SHA-1 hash key of the asset

REST equivalent: none (MCP only)

Get Model Details

GetModelDetails

Metadata, versions and usage for one model.

Models and versions Read-only Permission: read OAuth or API key

Get full details for a specific model including metadata, version history, asset usage count, and preview count.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
model_hash	string	required	SHA-1 hash key of the model (from models_h.model)

Related: SearchModels, GetModelVersions

Get Model Versions

GetModelVersions

Version history with training steps and quality scores.

Models and versions Read-only Permission: read OAuth or API key

Get version history for a model, including training steps, quality scores, and recommended flag.

Parameter	Type	Required	Description
model_hash	string	required	SHA-1 hash key of the model
include_deleted	boolean	optional	Include soft-deleted versions (default: false)

REST equivalent: none (MCP only)

Link Model To Asset

LinkModelToAsset

Manually link a model to an asset.

Models and versions Can write Permission: write OAuth or API key

Manually link a model to an asset (for non-ComfyUI sources where automatic detection is not available).

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
model_hash	string	required	SHA-1 hash key of the model
asset_hash	string	required	SHA-1 hash key of the asset
model_weight	number	optional	LoRA strength_model value (e.g., 0.75). Null for checkpoints.
detection_source	string	optional	How this link was discovered (default: manual_tag)

REST equivalent: none (MCP only)

Related: GetAssetModels

Search Models

SearchModels

Search the Model Library (LoRAs, checkpoints, UNETs).

Models and versions Read-only Permission: search OAuth or API key

Search the Model Library for models (LoRAs, checkpoints, UNETs, etc.) by name, type, or base architecture. Returns model entities with metadata, not assets. Use GetAssetModels to find assets by model.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
query	string	optional	Text search across model name, display name, and description. Supports partial matching.
model_type	string	optional	Filter by model type: lora, checkpoint, unet, clip, upscaler, controlnet, vae, embedding, ip_adapter, llm, etc.
base_model	string	optional	Filter by base architecture: sdxl, flux, sd15, sd3, sd35, pony, illustrious, noobai, hunyuan, etc.
limit	integer	optional	Maximum results to return (default: 50)
offset	integer	optional	Offset for pagination (default: 0)

Related: GetModelDetails

Prompts4 tools

Create, search and render prompts from the Prompt Library.

Create Prompt

CreatePrompt

Add a prompt to the Prompt Library.

Prompts Can write Permission: write OAuth or API key

Create a new prompt in the Prompt Library. Returns the prompt hash and version info.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Tenant UUID
prompt_text	string	required	The prompt text content (required)
name	string	optional	Human-readable prompt name
description	string	optional	Prompt description
target_model	string	optional	Target model (e.g., midjourney, dall-e, flux)
category	string	optional	Prompt category (e.g., landscape, portrait)
tags	string[]	optional	Prompt tags for organization

Related: GetPrompt, SearchPrompts

Get Prompt

GetPrompt

A prompt with its version history and evaluations.

Prompts Read-only Permission: read OAuth or API key

Get a prompt by hash ID with full version history and evaluations.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Tenant UUID
prompt_h	string	required	Prompt hub hash (40-char hex)

Related: SearchPrompts, RenderPrompt

Render Prompt

RenderPrompt

Substitute variables into a prompt template.

Prompts Read-only Permission: read OAuth or API key

Render a prompt template by substituting {{variable}} placeholders with provided values.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Tenant UUID
prompt_h	string	required	Prompt hub hash (40-char hex)
variables	object	optional	Template variables as key-value pairs (e.g., {"subject": "cityscape"})

Related: GetPrompt

Search Prompts

SearchPrompts

Search prompts by category and target model.

Prompts Read-only Permission: search OAuth or API key

Search prompts with optional category, target_model filters, and pagination.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Tenant UUID
category	string	optional	Filter by category
target_model	string	optional	Filter by target model
limit	integer	optional	Page size (default 20, max 100)
offset	integer	optional	Pagination offset (default 0)

Related: GetPrompt

Experiments and evaluations5 tools

Run structured comparisons: runs, scores and A/B results.

Compare Runs

CompareRuns

Record a pairwise A/B comparison between two runs.

Experiments and evaluations Can write Permission: write OAuth or API key

Create a pairwise A/B comparison between two experiment runs, recording which item wins on each scoring dimension.

Parameter	Type	Required	Description
collection_h	string	required	Experiment collection hash (40-char hex)
item_a	string	required	First run collection item hash (40-char hex)
item_b	string	required	Second run collection item hash (40-char hex)
winners	object	required	Dimension-to-winner mapping; each value is item_a's hash, item_b's hash, or the literal "tie" (e.g., {"quality": "<item_a_hash>", "coherence": "tie"})
evaluator_type	string	optional	Who/what performed the comparison (default: "human") enum: `human · vlm_assisted · embedding_similarity`
notes	string	optional	Comparison notes

Related: ScoreRun, GetExperimentSummary

Create Experiment

CreateExperiment

Create an experiment collection for structured comparison.

Experiments and evaluations Can write Permission: write OAuth or API key

Create an experiment collection for structured image comparison workflows (model benchmarking, prompt A/B testing, style evaluation). Returns the experiment collection hash.

Parameter	Type	Required	Description
tenant_id	string	optional	Tenant UUID
display_name	string	required	Human-readable experiment name
description	string	optional	Experiment description
hypothesis	string	optional	What this experiment tests
independent_variable	string	optional	What varies across runs (e.g., "prompt condition", "model", "LoRA")
control_variable	string	optional	What is held constant (e.g., "seed set", "resolution")
model_name	string	optional	Primary generation model (e.g., "FLUX.2 Dev")
workflow_name	string	optional	Generation workflow (e.g., "txt2img")
resolution	string	optional	Image resolution (e.g., "1024x1024")
domain_context	object	optional	Domain-specific metadata as JSON (e.g., {"grammar_version": "v3"})

Get Experiment Summary

GetExperimentSummary

Aggregated experiment results and outcomes.

Experiments and evaluations Read-only Permission: read OAuth or API key

Get aggregated experiment results: run count, condition breakdown, outcome tag distribution, and comparison count.

Parameter	Type	Required	Description
collection_h	string	required	Experiment collection hash (40-char hex)

Related: CreateExperiment, CompareRuns

Register Run

RegisterRun

Add an asset to an experiment as a run.

Experiments and evaluations Can write Permission: write OAuth or API key

Add an asset to an experiment as a run with full context (condition, seed, prompt, model, domain params).

Parameter	Type	Required	Description
collection_h	string	required	Experiment collection hash (40-char hex)
asset_h	string	required	Asset hash to register as a run (40-char hex)
condition_id	string	optional	Independent variable value for this run (e.g., "cond2b", "model_A")
variant_label	string	optional	Human-readable variant label (e.g., "Compiled prompt")
seed	integer	optional	Generation seed
prompt_text	string	optional	Exact prompt used for generation
model_name	string	optional	Model for this specific run (overrides experiment-level)
run_params	object	optional	Domain-specific run parameters as JSON
outcome_tags	string[]	optional	Outcome classification tags (e.g., ["text_literalization", "best_in_set"])
position	integer	optional	Position/order within the experiment

Related: CreateExperiment, ScoreRun

Score Run

ScoreRun

Score an experiment run on custom dimensions.

Experiments and evaluations Can write Permission: write OAuth or API key

Score an experiment run on user-defined dimensions. Creates an evaluation annotation. Dimensions are experiment-defined (e.g., quality, adherence, coherence).

Parameter	Type	Required	Description
collection_item_h	string	required	Collection item hash for the run to score (40-char hex)
scores	object	required	Scoring dimensions as key-value pairs (e.g., {"quality": 4, "coherence": 5}). Values are 1-5.
flags	object	optional	Boolean flags (e.g., {"prompt_leakage": true, "text_literalization": false})
evaluator_type	string	optional	Who/what performed the evaluation (default: "human") enum: `human · vlm_assisted · embedding_similarity`
comments	string	optional	Free-form evaluation comments

Related: RegisterRun, CompareRuns

Pipelines11 tools

Compose, save and execute multi-stage asset pipelines.

Action Stage

ActionStage

Run a single ACTION stage with side effects.

Pipelines Can write Permission: write OAuth or API key

Execute a single ACTION-category pipeline stage on a set of assets. Performs structural operations like moving, deleting, or archiving assets. Supported stage_type values: add_to_collection, move, delete, archive.

Parameter	Type	Required	Description
stage_type	string	required	The ACTION stage type to execute enum: `add_to_collection · move · delete · archive`
config	object	optional	Stage-specific configuration. add_to_collection: { path: "projects.nike" }. move: { from: "inbox", to: "approved" }. delete: { confirm: true }. archive: { confirm: true }.
assets	string[]	required	Array of asset hashes to act on
dry_run	boolean	optional	If true, simulates execution without side effects

REST equivalent: none (MCP only)

Related: TransformStage, OutputStage

Execute Pipeline

ExecutePipeline

Compose and run a multi-stage pipeline ad hoc.

Pipelines Can admin Permission: admin API key only

Execute a multi-stage asset pipeline. Compose select, filter, transform, action, output, and summarize stages into a single operation. Use dry_run: true to preview changes before committing. Stages by category: SELECT: search, collection, ids, diff (set comparison). FILTER: where, sort, limit, deduplicate, sample. TRANSFORM: set_tag, remove_tag, set_field, regex_replace, compute, set_visibility, set_owner, enrich (stub), approve (stub). ACTION: add_to_collection, move, delete, archive. OUTPUT: export (ADR-057 privacy-aware), notify (stub), tee (passthrough fan-out). SUMMARIZE: count, group_by, stats, histogram. Output stages require confirm: true and are skipped during dry-run. Summarize stages execute during dry-run to provide aggregation previews.

Parameter	Type	Required	Description
stages	object[]	required	Ordered list of pipeline stages. Must start with a select stage (search, collection, ids, or diff).
dry_run	boolean	optional	Preview what would happen without executing mutations. Transform/action stages show simulated side effects. Output stages are skipped. Summarize stages execute to provide aggregation previews. Default: false.
timeout_ms	number	optional	Maximum execution time in milliseconds (1000-60000). Default: 30000.

Related: SavePipeline, RunSavedPipeline

Filter Stage

FilterStage

Run a single FILTER stage on a set of assets.

Pipelines Read-only Permission: search OAuth or API key

Execute a single FILTER-category pipeline stage on a set of assets. Supported stage_type values: where (field filter), sort (order by field), limit (cap result count), deduplicate (remove duplicates), sample (random subset).

Parameter	Type	Required	Description
stage_type	string	required	The FILTER stage type to execute enum: `where · sort · limit · deduplicate · sample`
config	object	optional	Stage-specific configuration. sort: { by: "created_at", order: "desc" }. limit: { count: 20 }. where: { field: "tool", operator: "eq", value: "midjourney" }.
assets	string[]	required	Array of asset hashes to filter. Required for non-SELECT stages.
dry_run	boolean	optional	If true, simulates execution without side effects

REST equivalent: none (MCP only)

Related: SelectStage, TransformStage

List Pipelines

ListPipelines

List the tenant's saved pipelines.

Pipelines Read-only Permission: read OAuth or API key

List saved pipelines for the current tenant. Returns pipeline metadata including name, stage count, tags, and default execution settings. Use pipeline_definition_h from results with RunSavedPipeline to execute.

Parameter	Type	Required	Description
tags	string[]	optional	Filter by tags (e.g., ["weekly"])

List Pipeline Templates

ListPipelineTemplates

System and tenant pipeline templates.

Pipelines Read-only Permission: read OAuth or API key

List available pipeline templates for the current tenant. Returns system templates (available to all tenants) plus any tenant-specific templates. Use the pipeline_definition_h from results with POST /api/v1/pipelines/templates to clone a template into a new saved pipeline.

Related: SavePipeline, ListPipelines

Output Stage

OutputStage

Run a single OUTPUT stage to produce results.

Pipelines Can export Permission: export OAuth or API key

Execute a single OUTPUT-category pipeline stage on a set of assets. Produces outputs like exports, notifications, or tee copies. Supported stage_type values: export, notify, tee.

Parameter	Type	Required	Description
stage_type	string	required	The OUTPUT stage type to execute enum: `export · notify · tee`
config	object	optional	Stage-specific configuration. export: { preset: "client", confirm: true }. notify: { event_type: "pipeline.completed" }. tee: { action: { type: "add_to_collection", path: "backup" } }.
assets	string[]	required	Array of asset hashes for output
dry_run	boolean	optional	If true, simulates execution without side effects

REST equivalent: none (MCP only)

Related: ActionStage, SummarizeStage

Run Saved Pipeline

RunSavedPipeline

Run a saved pipeline by id or name with overrides.

Pipelines Can write Permission: write OAuth or API key

Execute a saved pipeline by ID or name. Supports overriding default_dry_run and default_timeout_ms at run time. Returns the same execution trace as ExecutePipeline. Provide either pipeline_definition_h (40-char hex) or pipeline_name (resolved automatically).

Parameter	Type	Required	Description
pipeline_definition_h	string	optional	40-char hex hash of the pipeline to run
pipeline_name	string	optional	Pipeline name (alternative to pipeline_definition_h). Resolved to hash automatically.
dry_run	boolean	optional	Override the saved default_dry_run. Defaults to pipeline's saved setting.
timeout_ms	number	optional	Override the saved default_timeout_ms (1000-60000)
vars	object	optional	Runtime variable injection (merged into pipeline context vars)

Related: SavePipeline, ExecutePipeline

Save Pipeline

SavePipeline

Create or update a named saved pipeline.

Pipelines Can write Permission: write OAuth or API key

Create or update a named saved pipeline. Provide pipeline_definition_h to update an existing pipeline (SCD Type 2 versioning preserves full edit history). Omit it to create a new pipeline. Pipelines are identified by slug (derived from name) and stored with full stage definitions.

Parameter	Type	Required	Description
name	string	required	Pipeline name (used to generate URL-safe slug). Must be unique per tenant.
stages	object[]	required	Ordered pipeline stage definitions (same format as ExecutePipeline stages)
description	string	optional	Human-readable description of what this pipeline does
default_dry_run	boolean	optional	Default dry_run setting when run without override (default: false)
default_timeout_ms	number	optional	Default timeout in ms, 1000-60000 (default: 30000)
tags	string[]	optional	Labels for organizing pipelines (e.g., ["weekly", "client-delivery"])
pipeline_definition_h	string	optional	40-char hex hash of existing pipeline to update. Omit to create new.

Select Stage

SelectStage

Run a single SELECT stage to choose assets.

Pipelines Read-only Permission: search OAuth or API key

Execute a single SELECT-category pipeline stage. SELECT stages are entry points that produce an initial asset set. Supported stage_type values: search (text query), collection (load from collection path), ids (explicit asset hashes), diff (set difference between two sub-selects).

Parameter	Type	Required	Description
stage_type	string	required	The SELECT stage type to execute enum: `search · collection · ids · diff`
config	object	required	Stage-specific configuration. search: { query: "tag:approved" }. collection: { path: "projects.nike", include_nested: true }. ids: { asset_ids: ["abc..."] }. diff: { set_a: {...}, set_b: {...}, mode: "only_in_a" }.
dry_run	boolean	optional	If true, simulates execution without side effects

REST equivalent: none (MCP only)

Related: FilterStage, ExecutePipeline

Summarize Stage

SummarizeStage

Run a single SUMMARIZE stage over a set of assets.

Pipelines Read-only Permission: read OAuth or API key

Execute a single SUMMARIZE-category pipeline stage on a set of assets. Produces aggregate data and statistics. Supported stage_type values: count, group_by, stats, histogram.

Parameter	Type	Required	Description
stage_type	string	required	The SUMMARIZE stage type to execute enum: `count · group_by · stats · histogram`
config	object	optional	Stage-specific configuration. count: { group_by: "tool" }. group_by: { field: "mime_type" }. stats: { field: "file_size" }. histogram: { field: "created_at" }.
assets	string[]	required	Array of asset hashes to summarize
dry_run	boolean	optional	If true, simulates execution without side effects

REST equivalent: none (MCP only)

Related: OutputStage, SelectStage

Transform Stage

TransformStage

Run a single TRANSFORM stage on a set of assets.

Pipelines Can write Permission: write OAuth or API key

Execute a single TRANSFORM-category pipeline stage on a set of assets. Modifies asset metadata or triggers AI enrichment. Supported stage_type values: set_tag, remove_tag, set_field, regex_replace, compute, set_visibility, set_owner, enrich, approve.

Parameter	Type	Required	Description
stage_type	string	required	The TRANSFORM stage type to execute enum: `set_tag · remove_tag · set_field · regex_replace · compute · set_visibility · set_owner · enrich · approve`
config	object	optional	Stage-specific configuration. set_tag: { tags: ["approved"] }. enrich: { operations: ["auto_tag"] }. set_field: { field: "status", value: "reviewed" }.
assets	string[]	required	Array of asset hashes to transform
dry_run	boolean	optional	If true, simulates execution without side effects

REST equivalent: none (MCP only)

Related: FilterStage, ActionStage

Automation and webhooks4 tools

Trigger pipelines from rules and receive event notifications.

Create Rule

CreateRule

Create a rule that runs a saved pipeline on events or schedule.

Automation and webhooks Can write Permission: write OAuth or API key

Create an automation rule that triggers a saved pipeline on events, schedules, or watch intervals. Provide pipeline_definition_h (40-char hex) or pipeline_name (resolved automatically). Trigger types: event (fires on asset/pipeline events), schedule (cron-based), watch (periodic query check).

Parameter	Type	Required	Description
name	string	required	Rule name (unique per tenant)
description	string	optional	Human-readable description of what this rule does
trigger_config	object	required	Trigger configuration with type discriminator. Event: { type: "event", event_type: "pipeline.completed" }. Schedule: { type: "schedule", cron: "0 9 * * 1" }. Watch: { type: "watch", query: "tag:unreviewed", interval_minutes: 60 }.
rate_limit_config	object	optional	Optional rate limiting config (e.g., { max_executions_per_hour: 10 })
pipeline_vars	object	optional	Variables to inject into pipeline context when rule fires
pipeline_definition_h	string	optional	40-char hex hash of the saved pipeline to trigger
pipeline_name	string	optional	Pipeline name (alternative to pipeline_definition_h). Resolved to hash automatically.

List Rules

ListRules

List automation rules with optional filters.

Automation and webhooks Read-only Permission: read OAuth or API key

List automation rules for the current tenant with optional filters. Returns rule metadata including name, trigger type, enabled status, and linked pipeline.

Parameter	Type	Required	Description
enabled	boolean	optional	Filter by enabled/disabled status
trigger_type	string	optional	Filter by trigger type enum: `event · schedule · watch`
tenant_id	string ·uuid	optional	Tenant UUID (optional - auto-injected from API key auth)

Related: CreateRule, TriggerRule

Register Webhook

RegisterWebhook

Subscribe a URL to event notifications.

Automation and webhooks Can admin Permission: admin API key only

Register a new webhook subscription to receive event notifications. Returns webhook ID and signing secret (shown once). Supports events: pipeline.completed, pipeline.failed, pipeline.export.completed, test.ping.

Parameter	Type	Required	Description
name	string	required	Human-readable name for the webhook subscription
url	string	required	HTTPS endpoint URL to receive webhook events (must be public, no private IPs)
events	string[]	required	Event types to subscribe to (e.g., ["pipeline.completed", "pipeline.failed"])
description	string	optional	Optional description of the webhook purpose
enabled	boolean	optional	Whether the webhook is enabled (default: true)
timeout_ms	number	optional	Request timeout in milliseconds, 1000-60000 (default: 10000)

Related: CreateRule

Trigger Rule

TriggerRule

Manually trigger automation rule processing.

Automation and webhooks Can write Permission: write OAuth or API key

Manually trigger automation rule processing. For schedule/watch: evaluates all due rules for the tenant. For event: dispatches to matching event-based rules. Returns execution results for each triggered rule.

Parameter	Type	Required	Description
trigger_type	string	required	Type of trigger to process: schedule (check cron-due rules), watch (check query-based rules), event (dispatch event to matching rules) enum: `schedule · watch · event`
event_type	string	optional	Event type to dispatch (required when trigger_type is "event", e.g., "pipeline.completed")
event_data	object	optional	Event payload data (optional, passed to matching event rules)
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.

Related: CreateRule, ListRules

Publishing and export9 tools

Publish collections, resolve public URLs and export assets.

Export Assets

ExportAssets

Export assets with a preset (not yet available over MCP).

Publishing and export Can export Permission: export OAuth or API key

Export assets with a privacy preset as ONE zip file and return a download link (download_url, valid 1 hour). Use preset share, portfolio, client, archive or custom. The number of assets per call is capped by the workspace plan's export batch limit (BATCH_LIMIT_EXCEEDED above it), and exports are limited per workspace per hour (EGRESS_QUOTA_EXCEEDED). Creator-private assets cannot be exported with an API key. The legacy export_configuration_h mode returns EXPORT_UNAVAILABLE.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	UUID of the target tenant for this export operation
asset_hs	string[]	required	Array of Asset Hashes (SHA1) to be exported
preset	string	optional	Export preset: share (social media, max privacy), portfolio (keeps attribution), client (business delivery), archive (full metadata), custom (user-defined) enum: `share · portfolio · client · archive · custom`
options	object	optional	Custom options (only when preset is "custom"). Fine-grained control over metadata stripping.
format	string	optional	Output format (preserve = keep source format) enum: `png · jpeg · webp · preserve`
export_configuration_h	string	optional	Legacy: Export Configuration Hash. Mutually exclusive with preset.

Related: ListExportPresets

Export Collection As PDF

ExportCollectionAsPdf

Render a collection as a PDF document.

Publishing and export Can export Permission: export OAuth or API key

Export a collection as a PDF document. Returns the PDF as a base64-encoded string along with page count and processing time metadata. The web API handles layout, pagination, and optional watermark removal.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
collection_h	string	required	Collection hash (SHA-1, 40 hex chars) to export
remove_watermark	boolean	optional	Whether to remove the Numonic watermark from the exported PDF. Default: false.

Get Asset Public URL

GetAssetPublicUrl

Reverse lookup of an asset's published URL.

Publishing and export Read-only Permission: read OAuth or API key

Reverse lookup: finds if an asset is in ANY published collection and returns the public URL. Returns one of three states: (1) Asset IS published with public_url, collection_path, preset, published_at; (2) Asset NOT published but in collections: lists collection paths; (3) Asset NOT in any collection: empty collections array.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Tenant UUID (optional - auto-injected from API key auth)
asset_h	string	required	Asset hash (SHA-1, 40 hex chars) to look up

Related: GetCollectionPublicUrls

Get Collection Public URLs

GetCollectionPublicUrls

Publication status and public URLs for a collection's assets.

Publishing and export Read-only Permission: read OAuth or API key

Get publication status and public URLs for all assets in a collection. Returns whether the collection is published, publication metadata, and URLs for each published asset.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
collection_h	string	required	Collection hash (SHA-1, 40 hex chars) to get public URLs for

List Export Presets

ListExportPresets

List export presets and their default options.

Publishing and export Read-only Permission: read OAuth or API key

List available export presets with their default options. Returns the preset configurations used by privacy-aware exports in the Numonic app and REST API (ADR-057).

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Tenant UUID (for tenant-specific presets if available)

REST equivalent: none (MCP only)

Related: ExportAssets

Publish Asset

PublishAsset

Publish one approved asset and get a stable public URL.

Publishing and export Can write Permission: write OAuth or API key

Publish one Approved asset on its own (outside any collection) and get a STABLE public URL that keeps working in deployed pages, unlike the 5-minute signed URLs from GetAssetDetails/SearchAssets. Only assets with status Approved can be published (set it with UpdateAsset). Embedded metadata is stripped and the image optimised per the presets (ADR-057); default privacy preset is 'share'. Returns public_url (the file, for <img src>) and page_url (/p/a/{slug}, public visibility only). Re-publishing refreshes the file at the same URL. Requires API-key authentication.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
asset_h	string	required	Asset hash (SHA-1, 40 hex chars) to publish
privacy_preset	string	optional	Privacy preset (ADR-057): share (default; title only on the public page), portfolio (+ tool, prompt), client (+ generation parameters), archive (keeps all metadata, no stripping) enum: `share · portfolio · client · archive`
visibility	string	optional	public (default): stable file URL plus a /p/a/{slug} page. unlisted: stable file URL only, never listed. enum: `public · unlisted`
publish_preset	string	optional	Image optimization preset: web-standard (default), high-quality, thumbnail enum: `web-standard · high-quality · thumbnail`

Publish Collection

PublishCollection

Publish a collection with privacy and publish presets.

Publishing and export Can write Permission: write OAuth or API key

Publish a collection with specified privacy and publish presets, making assets publicly accessible. Applies ADR-057 metadata stripping rules and generates public URLs.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
collection_h	string	required	Collection hash (SHA-1, 40 hex chars) to publish
privacy_preset	string	optional	Privacy preset for metadata stripping (ADR-057): share (strip workflow/models/GPS), portfolio (default, keeps attribution), client (business delivery), archive (keep all metadata) enum: `share · portfolio · client · archive`
publish_preset	string	optional	Image optimization preset: web-standard (default), high-quality, thumbnail enum: `web-standard · high-quality · thumbnail`

Unpublish Asset

UnpublishAsset

Remove an asset's standalone publication.

Publishing and export Can write Permission: write OAuth or API key

Remove an asset's standalone publication (created by PublishAsset): deletes the public file and retires its URL. Publications through a collection are not affected (use UnpublishCollection). Requires API-key authentication.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
asset_h	string	required	Asset hash (SHA-1, 40 hex chars) to unpublish

Related: PublishAsset

Unpublish Collection

UnpublishCollection

Remove a collection from public access.

Publishing and export Can write Permission: write OAuth or API key

Remove a collection from public access. Published assets are marked as unpublished and deleted from public storage.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant. Omit it: the server uses the tenant your credential (OAuth connection or API key) is bound to. A tenant_id that differs from the credential's tenant is rejected.
collection_h	string	required	Collection hash (SHA-1, 40 hex chars) to unpublish

Related: PublishCollection

Analytics and administration2 tools

Storage usage and search health for a tenant.

Get Search Analytics

GetSearchAnalytics

Search health summary with green/amber/red assessment.

Analytics and administration Read-only Permission: read OAuth or API key

Retrieve search analytics summary with health assessment (green/amber/red) for monitoring search quality. Returns zero-result rate, latency percentiles (P50/P95/P99), query-type breakdown, and top zero-result queries. Health thresholds: zero-result rate (<15% green, 15-25% amber, >25% red), P95 latency (<500ms green, 500-1000ms amber, >1000ms red).

Parameter	Type	Required	Description
period	integer	optional	Number of days to aggregate (1-90). Default: 7.
tenant_id	string ·uuid	optional	Optional: UUID of the tenant to query. If omitted, returns analytics for all tenants or current user's tenant.

Get Tenant Storage Details

GetTenantStorageDetails

Storage used versus plan limits for a tenant.

Analytics and administration Read-only Permission: read OAuth or API key

Retrieve storage usage details for a tenant including bytes used, GB used, storage limit, percentage used, and over-limit status. Helps monitor storage consumption and enforce storage quotas.

Parameter	Type	Required	Description
tenant_id	string ·uuid	optional	Optional: UUID of the tenant to query. If omitted, uses the tenant_id from auth context (current user's tenant).

Related: GetSearchAnalytics

Prospects and relationships13 tools

Outreach prospects, CRM contacts, replies and duplicate resolution.

Get Prospect State

GetProspectState

Full prospect state: profile, research, sequence, suppression.

Prospects and relationships Read-only Permission: read OAuth or API key

Return full prospect state: latest profile + research + state + suppression, plus all touches and replies, plus contact_link if hand-off has occurred.

Parameter	Type	Required	Description
tenant_id	string ·uuid	required	Required by this tool, but the value is ignored: it always acts on the canonical CRM tenant (super-admin only). Pass your own tenant UUID.
prospect_h	string	required	Prospect hub hash (SHA-1).

Get Relationship Summary

GetRelationshipSummary

Who this is, who owns it, what is next.

Prospects and relationships Read-only Permission: read OAuth or API key

One answer to "who is this, who owns it, what is next, and when is it due" for a CRM contact, prospect or organization (#2637). Resolves merged duplicate contacts to the canonical record, joins hand-off prospects and the organization, reconciles owner (prospect owner > contact assigned_to > open-task assignee, all candidates returned with owner_conflict), picks the earliest-due next action across open tasks, follow-ups, active outreach touches and re-engage dates, and returns a reverse-chronological activity list (touches, replies, notes, stage changes, tasks, deal updates). Same data as the admin CRM GUI panel. identity.organization_merged_from lists organizations merged into this one (#2636).

Parameter	Type	Required	Description
tenant_id	string ·uuid	required	Required by this tool, but the value is ignored: it always acts on the canonical CRM tenant (super-admin only). Pass your own tenant UUID.
entity_type	string	required	Which hub entity_id belongs to. enum: `contact · prospect · organization`
entity_id	string	required	Hub hash (SHA-1) of the contact, prospect or organization — e.g. a contact from SearchContacts or a prospect_h from SearchProspects.
activity_limit	integer	optional	Maximum activity entries returned (default 50).

List Dedup Candidates

ListDedupCandidates

List suspected duplicate CRM contacts or organisations.

Prospects and relationships Read-only Permission: read OAuth or API key

List suspected duplicate CRM contacts or organizations (#2636) from the identity-dedupe candidate queue, each with both records side by side (a and b), the match reasons, a score and a stale flag. Super-admin only. These are SUGGESTIONS for a human to review: never confirm or merge on your own, and always show the user both records side by side before asking which one to keep. Defaults to open candidates; use RefreshDedupCandidates to re-scan for new pairs first.

Parameter	Type	Required	Description
status	string	optional	Candidate status filter (default open). enum: `open · confirmed · rejected · all`
entity_type	string	optional	Optional: only contacts or only organizations. enum: `contact · organization`
limit	integer	optional	Page size (default 25).
offset	integer	optional

Log Outreach Touch

LogOutreachTouch

Append an outbound touch and advance the sequence.

Prospects and relationships Can write Permission: write OAuth or API key

Append a touch to the outbound log and advance the prospect outreach sequence state. channel accepts email, linkedin, discord, github, contact_form, or other (#1998). Both writes are append-only.

Parameter	Type	Required	Description
tenant_id	string ·uuid	required	Required by this tool, but the value is ignored: it always acts on the canonical CRM tenant (super-admin only). Pass your own tenant UUID.
prospect_h	string	required	Prospect hub hash (SHA-1).
touch	object	required
record_source	string	required

Related: LogReply, GetProspectState

Log Reply

LogReply

Record an inbound reply with triage classification.

Prospects and relationships Can write Permission: write OAuth or API key

Record an inbound reply with cold-outreach-studios reply-triage classification. Advances sequence state: positive → replied, not_now/wrong_person/unsubscribe/not_interested/bounced → suppressed, ooo leaves state untouched. bounced (#1998) is a delivery failure, distinct from every refusal classification. reply.refusal_class (#2000) optionally codes a refusal T (timing) or P (problem), only valid alongside a refusal-shaped classification. On positive reply, mints prospect_to_contact_l so lead-response v0.2 picks up the now-warm contact.

Parameter	Type	Required	Description
tenant_id	string ·uuid	required	Required by this tool, but the value is ignored: it always acts on the canonical CRM tenant (super-admin only). Pass your own tenant UUID.
prospect_h	string	required
reply	object	required
record_source	string	required

REST equivalent: none (MCP only)

Merge CRM Records

MergeCrmRecords

Merge two known-duplicate CRM records.

Prospects and relationships Can write Permission: write OAuth or API key

Merge two known-duplicate CRM contacts or organizations directly, or undo a merge (#2636). Super-admin only; audited. action=merge folds duplicate into survivor via a merge link; a merge is reversible only via action=unmerge on the duplicate. Organization merges do not merge the people belonging to them. Only call after the human has explicitly chosen which record survives; prefer ResolveDedupCandidate when a queue candidate exists.

Parameter	Type	Required	Description
action	string	required	enum: `merge · unmerge`
entity_type	string	required	enum: `contact · organization`
duplicate	string	required	Hub hash of the record to retire (or restore).
survivor	string	optional	Hub hash of the record to keep (required for merge).
reason	string	optional

Related: ResolveDedupCandidate

Refresh Dedup Candidates

RefreshDedupCandidates

Re-scan the CRM for duplicate candidates.

Prospects and relationships Can write Permission: write OAuth or API key

Re-scan the CRM for suspected duplicate contacts and organizations and update the candidate queue (#2636). Super-admin only; recorded in the CRM write audit. It only proposes candidates — it never merges anything. Returns pairs_found, new_candidates and updated_candidates; then call ListDedupCandidates to review.

Parameter	Type	Required	Description
entity_type	string	optional	Optional: scan only contacts or only organizations. enum: `contact · organization`

Related: ListDedupCandidates

Register Prospect

RegisterProspect

Prospects and relationships Can write Permission: write OAuth or API key

Register or update a cold-outreach prospect: writes prospects_h hub + tenant scoping link + prospect_profile_s, and optionally prospect_research_s (written when any research field is present, not only pain_hypothesis — #2000) and prospect_deal_s (when trial_start_date or agreed_price is present — #2000). At least one of email / linkedin_url / profile_url / handle / website required (#1997); keying precedence when more than one is present is email > linkedin_url > profile_url > handle > website. Append-only — re-calling adds new satellite rows.

Parameter	Type	Required	Description
tenant_id	string ·uuid	required	Required by this tool, but the value is ignored: it always acts on the canonical CRM tenant (super-admin only). Pass your own tenant UUID.
prospect	object	required	Prospect data. At least one of email / linkedin_url / profile_url / handle / website is required (validated server-side).
record_source	string	required	Origin tag, e.g. "cold-outreach-studios:studios-2026-q2".

Resolve Dedup Candidate

ResolveDedupCandidate

Record a human decision on a duplicate candidate.

Prospects and relationships Can write Permission: write OAuth or API key

Record a human decision on a duplicate candidate (#2636): confirm (merges the duplicate into the chosen survivor) or reject (marks the pair as not duplicates). Super-admin only; audited. ONLY call this after the human has explicitly chosen which record to keep (or to reject) having seen both records; never guess the survivor. survivor is required for confirm and must be one of the two records in the candidate pair.

Parameter	Type	Required	Description
candidate	string	required	Candidate id from ListDedupCandidates.
decision	string	required	enum: `confirm · reject`
survivor	string	optional	Hub hash of the record to keep (required for confirm; one of the pair).
note	string	optional

Search Contacts

SearchContacts

List CRM contacts in a pipeline with filters.

Prospects and relationships Read-only Permission: search OAuth or API key

List CRM contacts in a pipeline (community | enterprise | investor) with optional stage and free-text search. Wraps get_pipeline_contacts; returns the latest profile, pipeline stage, activity (last_contacted, next_follow_up), plus pipeline-specific satellite fields (investor: firm_name, investor_type, investment_amount, round, seis_eis_status). Default limit 50, max 200. tenant_id is auto-injected from API key auth.

Parameter	Type	Required	Description
tenant_id	string ·uuid	required	Required by this tool, but the value is ignored: it always acts on the canonical CRM tenant (super-admin only). Pass your own tenant UUID.
pipeline	string	required	Which CRM pipeline to list. 'investor' for fundraise contacts. enum: `community · enterprise · investor`
stage	string	optional	Optional pipeline-stage filter (e.g. "lead", "engaged", "diligence").
search	string	optional	Optional case-insensitive substring match against contact name and linkedin_url.
limit	integer	optional
offset	integer	optional

Related: GetRelationshipSummary

Search Prospects

SearchProspects

Filter prospects by campaign, status and ICP score.

Prospects and relationships Read-only Permission: search OAuth or API key

Filter prospects by campaign, current sequence status, minimum ICP score, vertical, account substring, or owner (#1999, exact match). Suppressed prospects (suppressed_until in the future) are excluded by default. Default limit 50, max 200. Each result row includes the current owner (null if unassigned).

Parameter	Type	Required	Description
tenant_id	string ·uuid	required	Required by this tool, but the value is ignored: it always acts on the canonical CRM tenant (super-admin only). Pass your own tenant UUID.
filters	object	optional

Related: GetProspectState

Set Prospect Owner

SetProspectOwner

Assign or reassign a prospect's owner.

Prospects and relationships Can write Permission: write OAuth or API key

Assign or reassign a prospect's owner (#1999). Append-only — writes a new prospect_owner_s row; never touches prospect_outreach_touch_s, so reassignment does not rewrite touch history. Set independently of prospect_outreach_touch_s.sent_by.

Parameter	Type	Required	Description
tenant_id	string ·uuid	required	Required by this tool, but the value is ignored: it always acts on the canonical CRM tenant (super-admin only). Pass your own tenant UUID.
prospect_h	string	required	Prospect hub hash (SHA-1).
owner	string	required
record_source	string	required

REST equivalent: none (MCP only)

Suppress Prospect

SuppressProspect

Suppress a prospect with a reason and optional end date.

Prospects and relationships Can write Permission: write OAuth or API key

Suppress a prospect with a reason and optional end-date. Marks all active sequences for the prospect as suppressed. unsubscribe is ALWAYS permanent (any suppressed_until is ignored). For not_interested / wrong_person, omit suppressed_until for permanent suppression or pass a future date for a finite one. not_now requires suppressed_until (the reengage date).

Parameter	Type	Required	Description
tenant_id	string ·uuid	required	Required by this tool, but the value is ignored: it always acts on the canonical CRM tenant (super-admin only). Pass your own tenant UUID.
prospect_h	string	required
reason	string	required	enum: `unsubscribe · wrong_person · not_now · not_interested`
suppressed_until	string,null ·date	optional	Future ISO date YYYY-MM-DD when suppression lifts. Omit (or null) for permanent suppression; required for not_now; ignored for unsubscribe (always permanent).
record_source	string	required

REST equivalent: none (MCP only)

Related: GetProspectState

Resources(5)

Resources are browsable read-only data that MCP clients can read for context — collection structure, storage quotas, available presets. Unlike tools, resources don't modify state.

resources/list resources/read:

{"jsonrpc":"2.0","method":"resources/read","params":{"uri":"numonic://collections"},"id":3}

numonic://storage

Storage Usage

resource

Tenant storage: GB used, quota, percentage, over-limit flag. Check before uploading large batches.

numonic://export-presets

Export Presets

resource

Available privacy presets with compliance metadata (EU AI Act, CA SB 942).

numonic://pipeline-templates

Pipeline Templates

resource

System and tenant pipeline templates. Browse before building custom pipelines.

numonic://asset/{asset_h}

Asset Details

resource · template

Full metadata for a specific asset. Pass the 40-character hex asset hash. (URI template)

Prompts(5)

Guided multi-step workflows that teach agents the canonical way to accomplish common tasks. They return pre-written instructions that chain multiple tool calls together.

prompts/get:

{"jsonrpc":"2.0","method":"prompts/get","params":{"name":"search-and-curate","arguments":{"query":"tool:midjourney AND tag:approved"}},"id":5}

Ingest & Organize

ingest-and-organize prompt

Upload a new asset and file it into the correct collection.

Workflow: StoreAsset → ListCollections → AddToCollection

Argument	Required	Description
filename	required	Name of the file being uploaded
mime_type	required	MIME type (e.g., image/png)
collection_path	optional	Target collection path

Export for Client

export-for-client prompt

Export assets with privacy-aware metadata stripping for client delivery.

Workflow: SearchAssets or GetCollectionAssets → ExportAssets

Argument	Required	Description
query_or_collection	required	Search query or collection hash
preset	optional	Privacy preset (default: client)

Audit Tenant Health

audit-tenant-health prompt

Assess storage usage, search index quality, and overall tenant health.

Workflow: GetTenantStorageDetails → GetSearchAnalytics → summarize

Explore Lineage

explore-lineage prompt

Trace a Midjourney asset's complete evolution chain through variations, upscales, and remixes.

Workflow: GetMidjourneyEvolutionChain → GetCreativeSession → synthesize

Argument	Required	Description
asset_h	required	Asset hash (40-char hex)
depth	optional	Maximum chain depth (default: 10)

Error Codes

The MCP server uses standard JSON-RPC 2.0 error codes.

Code	Name	Meaning
-32700	Parse Error	Malformed JSON in request body
-32600	Invalid Request	Missing jsonrpc or method field
-32601	Method Not Found	Unknown method name
-32602	Invalid Params	Missing or invalid parameters
-32603	Internal Error	Server-side exception

HTTP Status Codes

Parse errors and invalid requests return HTTP 400. All other errors (including tool failures) return HTTP 200 with the error in the JSON-RPC response body — per the JSON-RPC specification.

Tool-Level Errors

Tool errors are returned in the result's content array with isError: true:

{"content":[{"type":"text","text":"Error: …"}],"isError":true}

Protocol Details

Protocol	Model Context Protocol (JSON-RPC 2.0)
Transport	Streamable HTTP (POST)
Supported versions	2025-03-26 (primary), 2024-11-05 (backwards compatible)
Server name	Numonic-MCP-Server
Server version	1.0.0
Tools	72
Resources	5 (4 static + 1 URI template)
Prompts	5 guided workflows

MCP Server Reference: Tools, Resources & Client Setup