Preview availability

These docs are a developer preview of the initial create search and get search surface. The production API and documentation hostname are planned; a working deployment is not implied by this reference.

Available in the local implementationCopy Anchor Link

• Create a search and retrieve it by job_id.
• Quick and deep search as in the Sourcely app: language-model search phrases, provider ordering, and for deep search a shortlist, full-text reading and a second ranking. See How search works.
• Document and claim tracks, filters including domain filters, citations and enrichment options.
• Structured source maps and the enums listed in the reference.
• Validation errors, unknown-search errors and pollable terminal failures.
• Shared Redis storage with one-hour result retention by default, fenced updates and explicit cache-outage errors.
• Dashboard API key checks on create and get. A search is readable by the owning account only.
• Prepaid credits with Stripe top-ups and optional automatic top-up, managed on the API and MCP page in Sourcely. Subscription discounts of 15%, 35% and 50% for Pro, Ultra and Max.
• A USD quote on create and get, and a charged actual cost when the search finishes. Create returns 402 when the credit balance cannot cover the estimate.
• Per-key rate limits on search creation and polling, with 429 and Retry-After.
• A webhook when webhook_url is set. The POST is sent after the search finishes. Polling remains the source of truth.

The current server queues searches in Redis for a separate worker, which has a 10-minute execution timeout by default and may use heuristic/provider fallbacks. It does not place a hold. The credit balance decreases when a finished search reports its actual cost, and failed searches cost nothing.

Planned before public launchCopy Anchor Link

• Prepaid holds, so that searches started at the same moment cannot overdraw the balance.
• Idempotent creation. A concurrency limit separate from the per-key request windows.
• Account-scoped expiry tombstones, a public expiry timestamp and worker recovery.
• Clearer provider-failure reporting and recovery from whole-worker or Redis outages.

Deferred public capabilitiesCopy Anchor Link

Pagination actions, claim refetch, and public deletion are not part of the initial public reference. Those routes do not send a webhook. Page metadata remains on current models.

Naming and contract changesCopy Anchor Link

Public field names use snake_case. Current relevance ratings still use human-readable enum strings such as "Perfectly Relevant". These docs deliberately reproduce the implemented values; any move to snake_case enum values must update the API and version policy together.

Download the initial OpenAPI contract for exactly the two documented operations and their reachable schemas.