Your research. In your workflow.

1. Create an organisation key

An organisation administrator creates keys in API access. Copy the key once and store it in your server's secret manager. Do not place it in a URL, browser application or public repository. Keys expire after up to one year and can be revoked or replaced at any time.

2. Read an edition

Start with the manifest. Its edition ID pins every subsequent request to the same records, even when new research is published.

curl https://oreline.sirca.io/api/v1/manifest \
  -H "Authorization: Bearer $ORELINE_API_KEY"

curl "https://oreline.sirca.io/api/v1/facilities?edition=EDITION_ID&limit=100" \
  -H "Authorization: Bearer $ORELINE_API_KEY"

JSON responses contain schema_version, edition_id, data, next and request_id. Follow the relative next URL until it is null. A successful empty collection is not an error.

Available collections

All paths start with /api/v1/. Use ?id=RECORD_ID for a single record or ?limit=100 to page through a collection.

• companies
• facilities
• ownership
• ownership-disclosures
• capabilities
• relationships
• observations
• agreements
• sources
• source-links
• materials
• stages
• countries
• industrial-operations
• industrial-sources
• industrial-routes
• discovery-locations
• market-statistics
• outlook-indicators
• reference-releases

Rare-earth research uses the companies, facilities and evidence collections. Tungsten and germanium operations are available in industrial-operations, with their material, company, facility, process, quantities and source IDs. Those source IDs resolve in industrial-sources. They are not automatically merged with rare-earth entities.

Where disclosed, industrial operations include product specifications: grades, property values, units, minimum or maximum limits, typical values and source references. Search by grade using the q filter. Catalogue specifications do not establish available volume, manufacturing origin or qualification for a purchase.

Observations, agreements, capabilities and ownership disclosures have an evidence object that preserves the reviewed record, including scope, dates, units and source references. The OpenAPI specification documents these record shapes.

Discovery locations, market statistics and outlook indicators are separate collections. Discovery entries retain publisher classifications and may describe the same location in different releases. They are not additional verified operating facilities. Their source IDs resolve in reference-releases.

Use q to search names and titles, country for a country code (or the publisher's country name for discovery), material for a material slug or ID, and company for an operator or research-company ID. Filters match fields present on the record; they do not infer undisclosed ownership or upstream exposure.

3. Download or synchronise

Use entity=RECORD_ID to retrieve a facility's observations, relationships and source links, or agreements naming a company. It matches explicit record references, not inferred supply-chain connections.

The Python client downloads a complete edition into one directory, checks record counts and writes a COMPLETE marker only after every collection finishes. It needs Python 3 and no third-party packages.

export ORELINE_API_KEY="YOUR_KEY"
python3 oreline_sync.py

For CSV, add format=csv. Each page contains an ID column and a lossless JSON record column so nested evidence and multiple sources are retained. Pagination is in the HTTP Link header; the edition is in X-Oreline-Edition.

For later updates, list /editions, then request /changes?from=OLD_EDITION&edition=NEW_EDITION. Follow pagination. Changes identify added, updated and withdrawn records, with the new record for additions and updates. Withdrawn means removed from this published dataset, not necessarily closed or inactive. No inferred company mergers are applied.

Snapshot history begins when API publication is enabled. Reporting periods inside records can be older. We do not reconstruct historical editions from today's records or promise a fixed update schedule.

Usage and access

To resume an interrupted download, set ORELINE_EDITION to its edition ID and ORELINE_RESUME=1. Completed collections are checked and retained; incomplete collections restart. Without that option, the client never overwrites an existing download.

• Three active keys per organisation. Keys do not consume team seats.
• 10,000 successful requests per calendar month, resetting at midnight UTC on the first day.
• 60 requests per minute, shared by all keys. Use sequential pagination; simultaneous requests can receive a short retry response.
• Up to 100 records per page. Reduce the page size if a large response returns 413.
• No automatic overage charges. Usage is visible in API access and response headers. The workspace is unaffected by API quotas.

Access requires an active, unexpired organisation subscription. Scheduled cancellation retains access until the paid period ends. Past-due, canceled or expired access cannot read the API. Revocation takes effect on subsequent requests; downloaded records cannot be recalled. Organisation keys survive staff changes, so administrators should revoke keys that departing staff held.

Errors and retries

Errors return an error code and request_id. Share only the request ID with support, never your key.

• 400: invalid parameters or missing edition for pagination.
• 401: missing, expired or revoked key.
• 403: subscription access required.
• 404: unknown edition, collection or record.
• 413: request a smaller page.
• 429: honour Retry-After. A monthly quota response waits until next month.
• 503: retry with exponential backoff.

Successful data reads consume the monthly allowance. Rejected reads may still count toward the minute limit. Retrying a completed read counts again. Use server-to-server requests; browser cross-origin access is not enabled.

Use the evidence correctly

Missing quantities remain null. Capacity is not production; commercial agreements are not proof of current deliveries. Company-level evidence does not establish provenance for a particular part or shipment. Keep the source references, reporting period, qualifier and scope with each fact.

The API exposes shared published research only. It does not expose private reviews, uploaded documents, supplier responses or account information. Source references are included; third-party source documents are not redistributed. API access is for your organisation's internal use. Contact support@sirca.io to discuss redistribution or higher usage.