SOURCELY API PREVIEW
Response & request models
Every field, its meaning, type, nullability, and default — taken from the API contract.
A required field must be present. An optional field may be omitted. A type containing null also accepts a null value. The server currently serializes optional response fields as null rather than removing them.
Resolve entries in document.source_ids and claims[].source_ids through the top-level sources map. Scores are relative ranks, not confidence percentages.
See all enum values for the exact tokens referenced below. balance_after stays null. A webhook_url receives a POST when the search finishes; see Webhooks.
SearchRequest
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
text | string | Required | The text to find academic sources for. At least one character; there is no maximum length. Whitespace-only input is currently accepted by validation. Minimum length: 1. |
mode | SearchMode | Optional; default: "quick" | Search depth. quick fetches one Google Scholar page per generated keyword, falling back to Semantic Scholar, and keeps the provider order. deep fetches Semantic Scholar plus three Scholar pages per keyword, has a language model shortlist the 15 most promising sources, reads each one, and ranks them again with the analysis in hand. deep takes minutes rather than seconds. |
enrichment | EnrichmentLevel | null | Optional | Analysis level, independent of search depth. Omitted or null means medium for quick and high for deep. |
granularity | array<Granularity> | Optional | Result tracks to produce. Defaults to ["document"]. Use ["claim"] or ["document", "claim"] for claim-level results. An empty list currently falls back to document. |
max_claims | integer | Optional; default: 4 | Maximum identified claims to search, from 1 to 12. Defaults to 4. Only applies when the claim track is requested. Minimum: 1. Maximum: 12. |
citation_formats | array<CitationFormat> | null | Optional | Citation formats to populate. Omitted or null selects all five supported formats. An empty array disables citations. |
filters | Filters | null | Optional | Optional constraints on source selection. Omit or use null for no additional filtering. |
webhook_url | string | null | Optional | Optional http(s) URL. When set, the API POSTs the finished search here. The host must be public unless the deployment allows private URLs. Polling still works. |
Filters
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
year_from | integer | null | Optional | Inclusive lower publication-year bound. For example, 2020 keeps papers from 2020 onward. Papers without a known year are excluded when this is set. Omit or use null for no lower bound; use year_from <= year_to when both are set. |
year_to | integer | null | Optional | Inclusive upper publication-year bound. For example, 2024 keeps papers published in 2024 or earlier. Papers without a known year are excluded when this is set. Omit or use null for no upper bound. The current API does not validate year-range ordering. |
min_citations | integer | null | Optional | Minimum citation count, inclusive, as an integer >= 0. For example, 10 keeps sources with at least 10 citations. An unknown citation count is treated as zero for filtering, so it passes a threshold of 0 but not a positive threshold. Omit or use null to disable this filter. |
open_access | boolean | null | Optional | When true, require a non-empty pdf_url in the available source metadata. This is a PDF-availability check, not verification of licensing or download access. false, null or omission disables the filter; false does not mean closed-access only. |
paper_types | array<PaperTypeFilter> | null | Optional | Optional array of exact enum values: research and review. ["review"] keeps sources identified as reviews by a metadata-text heuristic; ["research"] excludes those sources. Both values disable this local distinction, but upstream providers can still favor reviews when review is included. Omit, use null or [] to avoid a paper-type restriction. This filter is not a peer-review guarantee. |
venue | string | null | Optional | Optional journal or publication-venue name, such as Nature. Forwarded to Semantic Scholar and Scholar URL-based providers; the current Serper adapter does not forward it. No exact venue check is applied after retrieval, so matching depends on the provider and unrelated venues can appear. Omit, use null or an empty string to disable the venue hint. |
include_keywords | array<string> | null | Optional | Optional array of strings that must all occur in the combined title, abstract and venue metadata. Local matching uses case-insensitive substrings, not whole words or full-paper text. For example, ["sleep", "memory"] requires both. Scholar providers also receive each entry as a required quoted phrase added to the query, which can narrow retrieval further. Omit, use null or [] to disable. Entries are trimmed and empty ones ignored. |
exclude_keywords | array<string> | null | Optional | Optional array of strings: exclude a source if any occurs in its title, abstract or venue metadata. Local matching uses case-insensitive substrings. For example, ["mouse", "rat"] excludes either match, including rat inside another word. Omit, use null or [] to disable. Do not include an empty string, because it matches every source. This does not inspect full-paper text. |
include_domains | array<string> | null | Optional | Optional array of host names. Only sources whose url or pdf_url is on one of these domains, or a subdomain, are returned. For example, ["ncbi.nlm.nih.gov"] also matches pubmed.ncbi.nlm.nih.gov. Entries may be given as bare hosts or full URLs; scheme, www. and paths are ignored. Scholar providers receive matching site: operators as well. Sources without a URL are excluded when this is set. Omit, use null or [] to disable. |
exclude_domains | array<string> | null | Optional | Optional array of host names. Any source whose url or pdf_url is on one of these domains, or a subdomain, is dropped. For example, ["wikipedia.org"] removes en.wikipedia.org results. Entries are normalized like include_domains. Scholar providers receive matching -site: operators as well. Omit, use null or [] to disable. |
preferred_domains | array<string> | null | Optional | Optional array of host names, most preferred first. Sources on these domains, or their subdomains, are moved ahead of other results; earlier entries rank ahead of later ones, and provider order is kept within each group. Other domains still appear. Omit, use null or [] to keep the provider ranking only. |
JobAccepted
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
job_id | string | Required | Opaque search identifier. Save it and pass it unchanged to GET /search/{job_id}. |
status | JobStatus | Optional; default: "queued" | Search state at acceptance. POST /search returns queued; GET /search/{job_id} provides the latest state. |
usage | Usage | null | Optional | USD quote for this search. estimated_cost is the maximum charge for the requested options. actual_cost is null until the search finishes. balance_after stays null; the dashboard holds the balance. |
SearchResult
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
job_id | string | Required | The same opaque search identifier returned by creation. |
status | JobStatus | Required | Overall job state. Inspect this even when the HTTP response is 200. |
result_type | string | Optional; default: "search" | Response discriminator; currently "search". |
document | DocumentTrack | null | Optional | Document-level result track, or null when not requested or not available. |
claims | array<Claim> | null | Optional | Identified claims and their results, or null when the claim track was not requested or is unavailable. |
sources | map<string, Source> | Optional | Source objects indexed by source ID. Resolve each document.source_ids or claim.source_ids entry in this map. |
usage | Usage | null | Optional | USD quote and charge for this search. estimated_cost is set when the search is created. actual_cost is null while it is running, the calculated charge when it completes, and zero when it fails. balance_after stays null; the dashboard holds the balance. |
metadata | SearchMetadata | null | Optional | Requested and actual claim-search counts, when available. |
DocumentTrack
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
source_ids | array<string> | Optional | Ordered source IDs for this document. Resolve each ID in the top-level sources map. |
scores | map<string, number> | Optional | Rank scores keyed by source ID for this document context. Larger values rank higher; these are not confidence percentages. |
search_queries | array<string> | Optional | The search phrases sent to the academic providers for this document, most relevant first. They are written from the submitted text by a language model, two for most texts and three past 3000 characters, and reused for later pages. Empty until the track has run. |
page | integer | Optional; default: 1 | Latest page fetched for this track, initially 1. A page is one provider results page of up to 10 sources for every search query, in query order, so a document page holds up to 20 sources, or 30 for texts over 3000 characters. Additional-page endpoints are outside the initial public surface. |
has_more | boolean | Optional; default: false | True when at least one search query filled its latest provider page, so another page may exist. It is not a guarantee or an initial-release pagination capability. |
status | TrackStatus | Optional; default: "pending" | State of this result track, distinct from overall job status. |
Claim
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
id | string | Required | Identifier for this claim within the search. |
span | string | Required | The identified claim text from the input. |
searched | boolean | Required | Whether a source search was attempted for this claim. Claims beyond max_claims can be returned with false. |
source_ids | array<string> | Optional | Ordered IDs pointing into the top-level sources map. |
scores | map<string, number> | Optional | Per-claim rank scores keyed by source ID; not probabilities. |
page | integer | Optional; default: 1 | Latest page fetched for this claim; initially 1. |
has_more | boolean | Optional; default: false | Heuristic indication of additional potential results. Claim refetch is deferred. |
status | TrackStatus | Optional; default: "pending" | State of the claim track. Unsearched claims may remain pending after the job completes. |
error | ErrorDetail | null | Optional | Safe error details for a failed claim, when present. |
Source
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
id | string | Required | Source identifier matching its key in the sources map. |
title | string | Required | Title of the academic source. |
authors | array<string> | Optional | Author names in provider order. An empty array means unavailable. |
year | integer | null | Optional | Publication year, or null when unknown. |
venue | string | null | Optional | Publication venue or journal, or null when unknown. |
abstract | string | null | Optional | Available abstract or provider summary; may be null. |
url | string | null | Optional | Source landing-page URL as a string, or null. Current validation does not enforce a URL format. |
pdf_url | string | null | Optional | Available PDF URL as a string, or null. |
citation_count | integer | null | Optional | Known citation count, or null when unavailable. Zero differs from an unknown count. |
score | number | null | Optional | Rank score attached to the source. Use the track-specific scores map when a source is shared between tracks. |
citations | Citations | null | Optional | Formatted citations. Null when citation_formats is empty; unrequested individual formats are null. |
enrichment | Enrichment | null | Optional | Analysis object, or null for enrichment none. Low only populates relevance; other levels may use fallback analysis. |
parsed_source | string | null | Optional | Text obtained during high enrichment, with abstract fallback when full text is unavailable. Not a guarantee of a complete paper. |
Citations
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
apa7 | string | null | Optional | APA 7 formatted citation, or null if not requested. |
mla9 | string | null | Optional | MLA 9 formatted citation, or null if not requested. |
ieee | string | null | Optional | IEEE formatted citation, or null if not requested. |
harvard | string | null | Optional | Harvard formatted citation, or null if not requested. |
bibtex | string | null | Optional | BibTeX entry, or null if not requested. |
Enrichment
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
level | EnrichmentLevel | Required | Effective enrichment level used for this source. |
relevance_rating | RelevanceRating | null | Optional | Qualitative relevance label. These current wire values are case-sensitive, human-readable strings; see the enum reference. |
analysis | string | null | Optional | Markdown explanation of the source’s relevance. Null at low enrichment. |
evidence | array<SupportingEvidence> | null | Optional | Supporting excerpts or findings and their explanations. Null at low; current fallbacks may produce fewer items than the intended 3–5. |
paper_type | PaperTypeClassification | null | Optional | Eight classification flags, or null at low enrichment. Heuristic/model output is not independent verification. |
SupportingEvidence
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
quote | string | Required | An excerpt or finding attributed to the source. Check against the original source before quoting it as verbatim. |
explanation | string | Required | Markdown explanation connecting the evidence to the research text. |
tag | string | Required | Short descriptive label for the evidence. |
PaperTypeClassification
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
peer_reviewed | boolean | Required | Whether analysis classifies the source as peer reviewed. |
renowned_author | boolean | Required | Whether analysis classifies the author as established in the field. |
top_tier_venue | boolean | Required | Whether analysis classifies the venue as top tier. |
meta_analysis | boolean | Required | Whether the source is classified as a meta-analysis. |
research_article | boolean | Required | Whether the source is classified as original research. |
review_article | boolean | Required | Whether the source is classified as a literature review. |
preprint | boolean | Required | Whether the source is classified as a preprint. |
randomized_control_trial | boolean | Required | Whether the source is classified as a randomized controlled trial. |
SearchMetadata
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
requested_max_claims | integer | null | Optional | Requested cap for claim searches. |
actual_max_claims | integer | null | Optional | Reported number of claims eligible under the request cap and extracted claim count. |
Usage
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
currency | string | Optional; default: "USD" | Currency for the amounts in this object. Currently USD. |
estimated_cost | number | null | Optional | Maximum USD charge for the requested mode, enrichment, source count, and claim count. Computed before the search runs. Null only on older records. |
actual_cost | number | null | Optional | USD reported for this search. Null while the search is still running. Zero when the search fails. On success, retrieval plus per-source enrichment for the sources actually returned, which can be below the estimate. A finished track with no sources still includes its retrieval fee. |
discount_percent | integer | null | Optional | Subscription discount already applied to estimated_cost and actual_cost, as a whole percentage: 15 for Pro, 35 for Ultra, 50 for Max, 0 without a subscription. Null only on older records. |
balance_after | number | null | Optional | Prepaid balance after this search. Null on this response. Create reads the dashboard balance and rejects with 402 when it cannot cover the estimate. The later usage report is what decreases it. |
ErrorResponse
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
error | ErrorDetail | Required | Structured API error details. |
ErrorDetail
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
code | string | Required | Stable machine-readable error identifier. |
message | string | Required | Human-readable description. Clients should branch on code, not this text. |
details | object | null | Optional | Optional additional error details; structure depends on the error. |
HTTPValidationError
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
detail | array<ValidationError> | Optional | Field-level validation issues returned by FastAPI; differs from the custom error envelope. |
ValidationError
| Field | Type | Presence / default | Meaning |
|---|---|---|---|
loc | array<string | integer> | Required | Location of the invalid value, such as ["body", "max_claims"]. |
msg | string | Required | Human-readable validation explanation. |
type | string | Required | Machine-readable validation issue type. |
input | any | Optional | Invalid input value when included by FastAPI. Avoid logging validation payloads containing sensitive text. |
ctx | object | Optional | Additional validation context, when present. |