API protocol trace
Build with the curaft content discovery API
Call the curaft content discovery API, inspect normalized semantic search results, handle pagination and rate limits, and preserve source attribution.
Open the API docsThe curaft content discovery API accepts one or more semantic queries and returns normalized content records with source details, publication dates, scores, story routes, and pagination metadata. The public endpoint is intended for evaluation and lower-volume use; its active quota is returned by the API index and rate-limit headers.
This walkthrough uses the current v1 contract published in curaft’s OpenAPI 3.0.3 file. It follows one request from query construction through the checks a production integration should make.
1. Send a minimal request
Start with one query, a small page size, and a freshness window. This makes relevance and response handling easier to inspect.
curl "https://curaft.com/api/v1/items?query=technical%20SEO&limit=10&time_range=last_30_days"No API key is required for the current public quota. Check /api/v1 for the active limit before making the API a production dependency.
2. Read the response by responsibility
| Response field | Use it for |
|---|---|
| data[].title | Display and selection; treat it as source-provided text. |
| data[].url | The original publication link. Preserve it for attribution and verification. |
| data[].summary | Triage and preview. Do not present it as a quotation from the source. |
| data[].source | Source name, favicon, identifier, and curaft source route when available. |
| data[].published_at | Freshness display and downstream filtering when a date is present. |
| data[].score | Relative semantic relevance when available, not an authority or quality score. |
| meta | Current page, page size, next page, total matches, and source count. |
| links.next | The server-built URL for the next page, or null when pagination is complete. |
3. Combine queries without hiding their purpose
Repeat the query parameter to combine related angles. Keep each value readable because it is also part of the integration’s audit trail.
curl "https://curaft.com/api/v1/items?query=AI%20search%20measurement&query=B2B%20AI%20visibility&sort=newest&limit=20"Use separate requests when the queries serve different screens, owners, or caching rules.
4. Cache the research result, not a claim of completeness
Cache repeated requests when the same query and page are used by several visitors. Store the request parameters with the response so the result can be traced back to its semantic instruction and freshness window.
The API is a discovery layer over the content available to curaft. A total count describes matches returned by that system for the request; it is not a count of every relevant page on the web. Interfaces should keep that scope clear when totals or source counts are displayed.
5. Handle the production boundaries
- 01
Rate limits
Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on successful responses. On HTTP 429, pause requests and respect Retry-After when it is present.
Completion signal: A traffic spike does not become a tight retry loop.
- 02
Partial metadata
Allow images, authors, scores, dates, and source routes to be absent. Build the UI around the title and original URL, which are the essential discovery fields.
Completion signal: A valid item still renders when optional fields are null.
- 03
Source attribution
Keep the original URL attached through caching, selection, and display. Generated summaries help with triage but do not replace the source publication.
Completion signal: A reader can reach the original context from every displayed item.
- 04
Contract changes
Generate or validate clients against the published OpenAPI file and monitor the API version rather than inferring the contract from one example response.
Completion signal: Integration tests fail clearly when a required field or route changes.
Contract and protocol references
- curaft API documentation
Interactive endpoint documentation and the current request parameters.
- curaft OpenAPI file
The machine-readable v1 contract used for client generation and validation.
- OpenAPI Specification 3.0.3
The specification version declared by the curaft OpenAPI document.
- HTTP 429 status code
The standards definition of Too Many Requests and optional Retry-After behavior.
Continue the research
Use a live topic for current material or move to the guide that owns the next part of the workflow.
Test the public endpoint with a real query
Start with the documented quota, inspect the source links and metadata, then contact us if the workflow needs commercial request volume.
Read the API docs