Knowledge curation

Living Systems Curator API

agents.biomimicry.living_systems

Creates, updates, or reuses living-system records from a bounded curation task. It is useful when a workflow has identified organisms or biological systems and needs stable IDs for later search, image selection, reporting, education, product discovery, or knowledge review.

POST /v1/agents/agents.biomimicry.living_systems/invokeagents:invoke

When to use it

Good fit

Normalizing organisms from research, extraction, spreadsheets, lesson plans, design tools, or product discovery into stable living-system IDs.
Checking existing records before creating new ones.
Keeping separate lists of records that were created, updated, or already sufficient for the submitted task.
Preparing IDs for image workflows, catalogs, reports, graph browsing, or review queues.
Submitting a narrow target list with enough context to resolve common-name ambiguity.

Use something else when

Authoritative taxonomy, occurrence, conservation-status, or distribution lookups.
Open-ended biological research before you have a bounded target list.
Direct image selection. Pass returned IDs to image selection or collection workflows.
Large unprioritized lists without an operation_budget and review plan.
Treating match_score as biological certainty. It is a relevance signal used during candidate review.

Use after a workflow, extractor, spreadsheet, lesson, catalog, or reviewer has identified a bounded list of organisms or biological systems that need stable living-system IDs.

Required inputs

inputs.task: Bounded curation instruction. Name the biological systems and the purpose of the curation.

Optional inputs

inputs.context: Additional constraints, downstream use, habitat, mechanism, material role, or review context.
inputs.operation_budget: Maximum add/update operations. Defaults to 30 and must be between 1 and 50.
inputs.organisms: Structured target list for reconciliation-friendly curation. Each item requires name and may include scientific_name, context, function, and source_ref.
configuration.webhook_url: Optional HTTPS URL for a terminal completion callback.
configuration.webhook_secret: Optional secret your service can use to verify callback signatures.
configuration.metadata: Opaque caller-owned metadata for reconciling the job with your workflow state.

What comes back

The completed job result is structured for integration. Preserve citations, warnings, confidence fields, and source context when the agent returns them.

Representative output fields

job_id: Identifier used to poll GET /v1/jobs/{job_id}.
status: Job state, such as queued, running, completed, failed, or canceled.
agent_id: The invoked agent, here agents.biomimicry.living_systems.
poll_url: Relative polling URL for the job result.
estimated_cost_usd: Acceptance-time estimate. The final charge can differ.
created_at / started_at / completed_at: Job lifecycle timestamps when available.
result.node_ids_created: IDs for records created during the run.
result.node_ids_updated: IDs for records updated during the run.
result.node_ids_sufficient: IDs for existing records judged sufficient for this task.
result.operations_used: Number of add/update operations consumed.
result.operations_remaining: Remaining add/update budget.
result.summary: Short human-readable run summary.
result.records: Reconciliation records that cover created, updated, and sufficient decisions.
result.warnings: Non-fatal conditions such as delayed search availability after a successful write.
result.charge_usd: Customer-visible charge for the completed billable run.

Result fields

operations[]: Add/update operation records with operation_type, node_id, canonical_name, success, and search_synced.
sufficient_records[]: Existing-record acknowledgements with node_id, canonical_name, match_score, and reason.
records[].decision: Decision label such as created, updated, or sufficient. Use this for reconciliation UIs.
records[].living_system_id: Stable living-system ID to persist for later workflow steps.
records[].canonical_name: Display label selected for the curated living-system record.
records[].rationale: Short explanation of why the record was created, updated, or reused.
records[].search_synced: Whether the record is already available through search-oriented discovery paths when that status is known.
warnings[].code: Machine-readable warning code. search_sync_pending means the returned ID is valid while search availability may lag.

How output is produced

Authenticates the API key and confirms agents:invoke permission.
Checks whether the account can start a billable curation job before work begins.
Accepts the request as an asynchronous job and returns job_id, status, agent_id, poll_url, estimated_cost_usd, and created_at.
Reads the narrow curation task and, when present, a structured organisms array.
Uses submitted context to reduce common-name ambiguity and prioritize the requested targets.
Searches existing records before creating anything and compares candidates by biological context, not name similarity alone.
Marks an existing record as sufficient when it already satisfies the submitted task.
Updates an existing record when it is the right entity but is missing useful context for the task.
Creates a new record when no existing record is adequate.
Consumes operation_budget only for add and update operations; search, read, and sufficient-record decisions do not consume that write budget.
Returns created, updated, and sufficient IDs plus records, warnings, and charge_usd when the completed job is billable.

Trust and caution

The workflow is designed to check existing records before creating new ones.
operation_budget limits add/update scope and makes broad tasks easier to control.
Created, updated, and sufficient records are separated so callers can review decisions.
Generated summaries and record decisions should be reviewed for high-stakes scientific, regulatory, health, or safety use.
Common names can be ambiguous. Add scientific_name, habitat, mechanism, function, and context when available.
sufficient means sufficient for the task. It does not certify that the record is complete for every future use.
The public result does not guarantee source citations for every created or updated record.

Runtime

Small, well-scoped tasks often complete in minutes. Runtime depends on target count, ambiguity, research needs, service latency, and operation_budget. Treat the endpoint as asynchronous and show queued, running, completed, and failed states.

Cost behavior

operation_budget limits add/update writes. It does not directly cap searches, reads, sufficient-record decisions, or reasoning iterations. The best public cost controls are narrow tasks, structured organisms, clear context, and a budget close to the expected number of changes. Use estimated_cost_usd before completion and charge_usd from the completed result for final customer-visible accounting.

Billing notes

The queued response includes estimated_cost_usd as an acceptance-time estimate.
Completed billable jobs include charge_usd in result. Treat charge_usd as the customer-visible final charge.
The final charge can be lower or higher than the estimate depending on target count, ambiguity, context, and work performed.
Organization credits are deducted for billable completed work according to the account's public API pricing.
Detailed execution accounting is handled by the platform rather than exposed as response fields.

Representative input

{
  "inputs": {
    "task": "Ensure living-system records exist for Namib desert beetle, lotus leaf, and Saharan silver ant.",
    "context": "These records will support a lesson on passive water and heat management strategies. Prefer species-level records when evidence is available.",
    "operation_budget": 3,
    "organisms": [
      {
        "name": "Namib desert beetle",
        "scientific_name": "Stenocara gracilipes",
        "function": "passive water collection",
        "context": "Fog-harvesting surface structures",
        "source_ref": "lesson-organism-001"
      },
      {
        "name": "Lotus leaf",
        "function": "self-cleaning surface",
        "context": "Surface wetting and contamination removal",
        "source_ref": "lesson-organism-002"
      },
      {
        "name": "Saharan silver ant",
        "scientific_name": "Cataglyphis bombycina",
        "function": "passive heat management",
        "context": "Desert thermoregulation",
        "source_ref": "lesson-organism-003"
      }
    ]
  },
  "configuration": {
    "metadata": {
      "external_run_id": "lesson-water-heat-001"
    }
  }
}

Queued response

{
  "job_id": "job_7f3a2b1c",
  "status": "queued",
  "agent_id": "agents.biomimicry.living_systems",
  "poll_url": "/v1/jobs/job_7f3a2b1c",
  "estimated_cost_usd": 0.12,
  "created_at": "2026-05-27T21:30:00Z"
}

Representative completed result

{
  "job_id": "job_7f3a2b1c",
  "agent_id": "agents.biomimicry.living_systems",
  "status": "completed",
  "created_at": "2026-05-27T21:30:00Z",
  "started_at": "2026-05-27T21:30:02Z",
  "completed_at": "2026-05-27T21:32:18Z",
  "result": {
    "node_ids_created": [
      "ls_9f1a"
    ],
    "node_ids_updated": [
      "ls_2c8b"
    ],
    "node_ids_sufficient": [
      "ls_6d4e"
    ],
    "operations_used": 2,
    "operations_remaining": 1,
    "summary": "Created 1 new living system, updated 1 existing living system, and reused 1 already-sufficient record.",
    "operations": [
      {
        "operation_type": "ADD",
        "node_id": "ls_9f1a",
        "canonical_name": "Saharan Silver Ant",
        "success": true,
        "search_synced": false
      }
    ],
    "sufficient_records": [
      {
        "node_id": "ls_6d4e",
        "canonical_name": "Lotus Leaf",
        "match_score": 0.91,
        "reason": "Existing record already includes the relevant self-cleaning and surface-wetting context."
      }
    ],
    "records": [
      {
        "decision": "created",
        "living_system_id": "ls_9f1a",
        "canonical_name": "Saharan Silver Ant",
        "rationale": "Created during this curation run.",
        "search_synced": false
      },
      {
        "decision": "sufficient",
        "living_system_id": "ls_6d4e",
        "canonical_name": "Lotus Leaf",
        "rationale": "Existing record already includes the relevant self-cleaning and surface-wetting context.",
        "search_synced": null
      }
    ],
    "warnings": [
      {
        "code": "search_sync_pending",
        "message": "The source record was written, but search sync did not complete during the run. The returned ID is valid; search results may lag.",
        "node_id": "ls_9f1a",
        "canonical_name": "Saharan Silver Ant"
      }
    ],
    "charge_usd": 0.084
  }
}

Errors and retries

Common failures

Missing inputs.task.
inputs.operation_budget outside the supported 1 to 50 range.
Malformed inputs.organisms entries, such as items without a name.
401: the API key is missing or invalid.
403: the key does not have agents:invoke scope or this agent is not available to the caller.
402: the account does not have enough credits to start the job.
400: webhook_url is not HTTPS in production.
429: the client exceeded the allowed request rate.
503: the platform could not accept or complete the curation job at that time.
failed: the accepted job could not complete, often because required input was missing, input shape was invalid, curation failed, or billing could not be completed.
404: the job ID is wrong, expired, or not owned by the caller.

Retry guidance

After a job_id is returned, poll GET /v1/jobs/{job_id} with bounded exponential backoff.
Honor Retry-After on 429 responses.
Polling retries are safe until the job reaches a terminal status or the result retention window expires.
Correct validation, authentication, permission, or credit failures before retrying.
Because this endpoint can create durable records, retry an invoke only with your own idempotency guard, such as a stored external_run_id and target list.
Use callbacks for unattended workflows, but keep polling as a reconciliation fallback for missed or delayed delivery.
If results are too broad, narrow the target list or add scientific_name, habitat, mechanism, function, and context instead of repeating the same request.

Composition ideas

Research to image workflow

Run a research or extraction step, normalize organism names, call Living Systems Curator, store returned IDs, then pass those IDs to image selection or catalog generation.

Curriculum library workflow

Curate organisms for a lesson objective, review records and warnings, then use returned IDs to build cards that link systems to functions and strategies.

Product discovery workflow

Convert candidate organisms behind product ideas into living-system records, then use records for comparison tables, galleries, and function-based browsing.

Review and reconciliation workflow

Store source_ref in inputs.organisms, then join your local source items to result.records by order, name, and returned living_system_id.

Application fit

Research-to-ID normalization after organism extraction.
Educational organism catalogs, lesson cards, and classroom biomimicry libraries.
Biomimicry exploration assistants that need reusable biological entities.
Regenerative design workflows that curate place-relevant organisms before visual or analogy steps.
Media workflows that need stable living-system IDs before rights-aware image selection.
Knowledge-base QA, deduplication, and record improvement workflows.
AI assistant memory that should refer to durable biological entities across sessions.
Product discovery boards and material inspiration catalogs.

Back to agent catalog