Use API Endpoint Sources in Cortex
API Endpoint sources poll structured JSON APIs. They work best when the publisher already exposes item data directly and you can define the extraction paths clearly.
Add the endpoint URL plus JSONPath expressions that tell Cortex where the item array and item fields live inside the response.
If the API needs authentication, reference a stored credential and optional request headers instead of embedding secrets directly in the source config.
- Internal systems that already expose structured JSON
- Third-party SaaS or vendor APIs with stable response shapes
- Authenticated endpoints your team already manages access to
- Cases where structured fields are more reliable than scraping
API Endpoint is the structured-data alternative to Web scraping. Use it when the publisher already exposes a JSON API and you want Cortex to poll that API directly instead of reading rendered pages.
API Endpoint Setup
Start with the request URL, then define the extraction paths that turn the JSON response into one item stream. Only add credential refs or request headers if the endpoint actually requires them.
Key Configuration Fields
| Name | Description |
|---|---|
| URL |
Use the JSON endpoint you actually want Cortex to poll. API Endpoint is best when the upstream already exposes structured data directly.
Example
https://api.example.com/items
|
| Items Path |
Point at the array of items inside the JSON response. Cortex uses this to decide which elements become candidate items.
Example
$.items[*]
|
| URL Path |
Point at the canonical URL inside each item object so Cortex can identify and deduplicate items correctly.
Example
$.url
|
| Text Path |
Point at the main text body or description field Cortex should ingest for each item.
Example
$.body
|
| Bearer Credential Ref |
Use a stored credential ref when the endpoint requires authentication. Keep secrets in the credential system, not inline in the source config.
Example
credref_api
|
Keep secrets in stored credentials. For the full field reference, see Create Source in the API docs and use External Credentials for provider setup context.
Examples
These examples show common structured-data patterns for API Endpoint sources.
GitHub Repository Pull Requests
Authenticated API polling against a top-level array response. Use this when the upstream already exposes the exact item collection you want as one list endpoint.
JSONPath: $[*] selects every element in a top-level array. Use $.items[*] when items are nested under a key.
GitHub Repository Issues Search
Authenticated API polling against a nested search-results payload. Use this when the source is defined by query logic rather than a fixed collection endpoint.
JSONPath: $.items[*] selects each element inside a nested "items" array. Match this to the actual response shape.
Troubleshooting & FAQ
The source runs, but no items are extracted.
The most common issue is a wrong Items Path.
Verify that it points at the array inside the actual JSON response shape, not at the whole response object.
The API responds, but Cortex still cannot use the items properly.
Recheck URL Path and Text Path first.
Without a stable canonical URL or usable main text field, the connector can technically poll the endpoint but still fail to produce a good item stream.
How should authenticated endpoints be configured?
Store the credential separately, then reference it with Bearer Credential Ref.
Keep any stable non-secret request metadata in Request Headers JSON rather than embedding raw secrets in the source itself.