Speconaut API reference

Authentication

Use the API base assigned to your account. Keep API keys on your server.

Authorization: Bearer $SPECONAUT_API_KEY

Ask

POST/v1/askAccount adapter / controlled store pilot

Ask a product question with source references and follow-up context. The configured backend selects the store; caller labels do not grant access.

curl --fail-with-body "$SPECONAUT_API_BASE/v1/ask" \
  -H "Authorization: Bearer $SPECONAUT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"question":"What is the Harbor Scarf made of?"}'

{
  "question": "Can I machine wash it?",
  "context": {
    "version": 1,
    "previous": {
      "user": "What is the Harbor Scarf made of?",
      "assistant": "The Harbor Scarf source lists acrylic."
    }
  }
}

Responses include request_id, answer, sources, route, mode, and usage. Inspect the sources instead of treating an AI answer as a stock or completeness guarantee. The adapter forwards question and context; separate session-creation, output-format selection, and public product-detail endpoints are not implemented contracts.

Source search

GET/raw-text/searchOperator preview / customer gateway pending

Search V3 source metadata by name, code, or filename. This is not full-text search over every file and does not call AI or load RAW_TEXT bodies.

Query

q: 1-500 characters. Optional ext=md or json. Default limit=20, maximum 32.

Coverage

coverage: bounded_candidates, exhaustive: false. No candidates does not prove that the whole store lacks a product.

Read budget

32 candidates, 8 terms, up to 4 term shards per term and 48 details. Exact filenames can add one storage HEAD.

POST/raw-text/checkOperator preview

Accepts store, q, and optional filename. Returns up to 8 candidates. An exact stored file may be found before index publication. If the index is unavailable, an exact-file result is explicitly partial; an outage is never reported as proof of absence.

Missing

Track unanswered demand in a store-owned backlog. Current entries are manual. Automatic Ask-to-Missing events and durable create deduplication are not enabled.

All three are operator-preview routes behind a separate gate, not customer-key endpoints. Archive retains the record. Resolve is an owner decision, not an automatic assertion that a source is published or searchable.

An application can build a review or sourcing workflow around Missing once its authorized integration is provisioned. Never derive an inventory verdict merely from an empty search, and never turn a 503 into a missing-product event. See the workflow.

Add & update

POST/raw-text/uploadOperator preview / publication required

Accepts store, filename, and source content. Markdown and JSON uploads are limited to 256 KiB. Creation is conditional; a racing or duplicate filename returns a conflict rather than silently replacing data.

Replacement requires overwrite: true and the exact observed if_match revision. The operator read route GET /raw-text/file supplies that revision. GET /raw-text/list is paginated storage inventory, not product search.

A saved source returns pending_directory_publish in V3 mode. Publication and a representative retrieval check are still separate; there is no automatic customer ingestion queue or public reindex endpoint advertised here.

Delete

POST/raw-text/deleteDisabled / recovery safeguards required

The prepared operator contract requires store, source key, observed if_match, and confirm: true. It is not a public DELETE endpoint and does not accept a permanent source-version deletion request.

Real deletion remains disabled until versioned recovery, retention, and permissions have been verified. A feature flag alone is insufficient. Missing Archive is a separate task-status operation; it neither deletes a product file nor provides privacy erasure.

Errors & retries

The metered Ask preview supports an Idempotency-Key header of 1-128 printable ASCII characters. Reuse it with the same request after an uncertain result; it is not a blanket guarantee for every route. Source creation and Missing creation do not yet provide durable operation-level idempotency.

Pricing: tokens vs requests

Development proposal, not active billing. Missing, Add/update and Delete use no AI tokens. Validation, JSON/Markdown handling, hashing, revision checks and storage operations do not call a model. A Missing record's text length is not converted into tokens.

Detecting a gap during a conversation can still use the Ask planner/answer layer. Those reported tokens belong to Ask once, not to the Missing storage API a second time. Automatic customer Ask-to-Missing logging is not enabled yet. Any future AI enrichment, classification or translation must be explicit and separately metered, never silently added to a data request.

One successful API call is one request, not one internal storage operation or one returned product. Missing list is one page of up to 25 records; create and each status change are separate calls. Add/update accepts one file up to 256 KiB. A prior check/preview call is not secretly included in an upload, and V3 search/check has no approved customer tariff yet.

Validation errors, disabled Delete, service failures and verified idempotent replays have a proposed request fee of $0. Retry protection and durable billing reconciliation must exist before paid source-management launch. Repeating a mutation without that protection can still create a second operation today; never retry an uncertain write blindly.

Successful operator responses report operation_usage with requests: 1, ai_used: false, zero input/output tokens, and billing_status: unbilled_operator_preview. This is request classification, not a durable usage log, an invoice, or a wallet deduction.

Speconaut AI

The token proposal retains a $0.001 minimum per successful Ask request only. Reported planner, answer and explicit retry tokens are counted once. A deterministic Ask answer can have zero provider tokens and still carry this disclosed platform minimum; the minimum is not inherited by Missing, Add or Delete.

Separate storage and publication

Storage proposal: $0.10 / GiB-month, measured over retained bytes rather than product count. Old versions and generated artifacts occupy storage too; deleting the visible file does not erase recovery versions. No automatic storage meter or storage debit is implemented.

Upload does not include publication/reindexing, AI enrichment, crawling, translation, or unlimited hosting. The current V3 builder is a deterministic full-store rebuild, not incremental ingestion. A future publication job needs its own approved estimate and budget before execution. This preview starts no paid background job.

The request prices are a starting proposal, not a guaranteed margin. Customer rollout remains blocked on account-to-store authorization, operation idempotency, rate/in-flight caps, enforceable duration/byte budgets, audit/retention controls, and measured infrastructure costs. Larger cold V3 metadata reads are not covered by the flat request rates above.

Account & usage

Account routes use the signed-in account JWT, not the developer Ask key. Implemented routes include GET /v1/me, GET /v1/usage, GET /v1/billing, POST /v1/api-keys, and DELETE /v1/api-keys/{keyId}.

The USD metering candidate returns token counts, charge_usd, and exact integer charge_microusd. Usage can include planner and answer calls. Pricing is a versioned proposal and environment-dependent; do not assume the production adapter uses the local USD policy.

Manage keys, inspect usage, or review the account's billing configuration. No API secrets are collected or executed by this reference page.

OpenAPI

Download the account-adapter OpenAPI preview. The existing URL is retained for compatibility; its version identifies the updated development contract.

The schema covers implemented Ask and selected account routes only. Operator source-management routes above are intentionally excluded until a customer gateway exists. Unimplemented product, session, and SMS placeholders have been removed. No public production server is implied by the schema.

Return to the documentation for source preparation, store boundaries, and lifecycle guidance.