> ## Documentation Index
> Fetch the complete documentation index at: https://docs.context.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Setting up Context.dev for a user? Follow https://docs.context.dev/agent-quickstart.md. Start by signing the user up and getting an API key through https://www.context.dev/auth.md; application code reads CONTEXT_DEV_API_KEY.
# Search news
> Find company news by name, domain, ticker, or ISIN. Filter articles and continue through results with a cursor.
1 credit per 10 results
See the [guide](/news/overview) for examples and usage.
## OpenAPI
````yaml POST /news/search
openapi: 3.1.0
info:
title: Context.dev API
description: >-
Scrape, crawl, search, and monitor websites, and retrieve brand, people, and
news data.
version: 1.0.0
servers:
- url: https://api.context.dev/v1
security: []
tags:
- name: Webhooks
description: Inspect and retry batch and monitor webhook deliveries.
- name: Logs
description: Read your organization's API request logs.
- name: Usage
description: Read your organization's credit balance and usage history.
- name: Agent Feedback
description: Report API issues and documentation mismatches.
- name: Batches
description: Scrape many pages or crawl a site asynchronously.
- name: Monitors
description: Watch websites for exact or meaningful changes.
- name: News
description: Search live and historical news about a company.
- name: Answers
description: Answer a research task from the live web in the JSON shape you ask for.
paths:
/news/search:
post:
tags:
- News
summary: Search news
description: >-
Find company news by name, domain, ticker, or ISIN. Filter articles and
continue through results with a cursor.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
searchBy:
type: object
properties:
type:
type: string
enum:
- entity
description: How to search. Only entity search is supported.
entity:
oneOf:
- $ref: '#/components/schemas/NewsSearchEntityByName'
- $ref: '#/components/schemas/NewsSearchEntityByDomain'
- $ref: '#/components/schemas/NewsSearchEntityByTicker'
- $ref: '#/components/schemas/NewsSearchEntityByIsin'
discriminator:
propertyName: type
mapping:
name: '#/components/schemas/NewsSearchEntityByName'
domain: '#/components/schemas/NewsSearchEntityByDomain'
ticker: '#/components/schemas/NewsSearchEntityByTicker'
isin: '#/components/schemas/NewsSearchEntityByIsin'
description: >-
The company to search news for, identified by name,
domain, ticker, or ISIN.
required:
- type
- entity
additionalProperties: false
description: What to search for.
filterBy:
type: object
properties:
sourceDomain:
type: array
items:
type: string
minLength: 1
maxLength: 253
minItems: 1
maxItems: 3
description: Publisher domains to include. Up to 3.
sourceCountry:
type: array
items:
type: string
enum:
- ae
- ar
- au
- ca
- cg
- ch
- cl
- cz
- de
- fi
- fr
- gb
- hk
- il
- in
- jp
- kr
- mx
- ng
- nl
- qa
- sa
- se
- sg
- us
- za
minItems: 1
maxItems: 3
description: >-
Publisher countries to include, as lowercase ISO 3166-1
alpha-2 codes. Up to 3.
articleLanguage:
type: array
items:
type: string
enum:
- ar
- de
- en
- es
- fr
- hi
- it
- ja
- ko
- nl
- pt
- ru
- zh
minItems: 1
maxItems: 3
description: Article languages to include. Up to 3.
articleType:
type: array
items:
type: string
enum:
- editorial
- press_release
- regulatory_filing
- advisory
minItems: 1
maxItems: 3
description: Article types to include. Up to 3.
date:
type: object
properties:
from:
type: integer
description: >-
Inclusive start of the published-at window, in epoch
milliseconds.
to:
type: integer
description: >-
Inclusive end of the published-at window, in epoch
milliseconds.
additionalProperties: false
description: >-
Published-at window in epoch milliseconds. from must be
before or equal to to.
additionalProperties: false
description: >-
Optional result filters. Use at most one of sourceDomain,
sourceCountry, articleLanguage, or articleType. A date range
may accompany that category; date.from must not exceed
date.to.
allOf:
- not:
required:
- sourceDomain
- sourceCountry
- not:
required:
- sourceDomain
- articleLanguage
- not:
required:
- sourceDomain
- articleType
- not:
required:
- sourceCountry
- articleLanguage
- not:
required:
- sourceCountry
- articleType
- not:
required:
- articleLanguage
- articleType
sortBy:
type: object
properties:
type:
type: string
enum:
- relevance
- newest
description: Result ordering.
default:
type: newest
required:
- type
additionalProperties: false
description: Result ordering. Defaults to newest.
limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: Maximum results to return. Defaults to 10.
cursor:
type:
- string
- 'null'
maxLength: 300
description: >-
Opaque next_cursor from the previous response, or null for
the first page.
tags:
$ref: '#/components/schemas/RequestTags'
required:
- searchBy
additionalProperties: false
example:
searchBy:
type: entity
entity:
type: domain
domain: stripe.com
responses:
'200':
description: Company news results
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: >-
Stable unique identifier for this article. Use it to
deduplicate or reference an article across requests.
story_id:
type: string
description: >-
Shared by articles covering the same story on the
same day. Use it to group or collapse syndicated
copies of one announcement across outlets.
url:
type: string
format: uri
description: Link to the article on the publisher site.
title:
type: string
description: Article headline.
description:
type:
- string
- 'null'
description: >-
Short summary or excerpt of the article, when the
publisher provides one.
language:
type:
- string
- 'null'
description: >-
Language the article is written in, as a lowercase
ISO 639-1 code such as en. Null when unknown.
authors:
type: array
items:
type: string
description: Bylined authors. Empty when no byline is available.
image_url:
type:
- string
- 'null'
description: Lead image for the article, when one is available.
published_at:
type:
- string
- 'null'
format: date-time
description: >-
When the article was published, as an ISO 8601
timestamp. Null when the publisher does not state a
reliable date.
type:
type: string
enum:
- editorial
- press_release
- regulatory_filing
- advisory
description: >-
Kind of coverage. Use it to separate independent
reporting (editorial) from company-issued content
(press_release, regulatory_filing, advisory).
source:
type: object
properties:
name:
type: string
description: Name of the publication, such as Reuters.
domain:
type: string
description: Website domain of the publication.
direct:
type: boolean
description: >-
True when Context observed this article in the
publisher-owned feed.
required:
- name
- domain
- direct
description: The publication that published the article.
match:
type: object
properties:
level:
type: string
enum:
- primary
- secondary
description: >-
primary when the article is mainly about the
company, secondary when the company is mentioned
but is not the main subject.
confidence:
type:
- number
- 'null'
minimum: 0
maximum: 1
description: >-
How confident the match is, from 0 to 1. Null
when a score is unavailable.
required:
- level
- confidence
description: >-
How the article relates to the company you searched
for.
required:
- id
- story_id
- url
- title
- description
- language
- authors
- image_url
- published_at
- type
- source
- match
description: Articles matching the search, in the requested order.
has_more:
type: boolean
description: True when more results are available beyond this page.
next_cursor:
type:
- string
- 'null'
description: >-
Pass as cursor in the next request to fetch the following
page. Null when there are no more results.
meta:
type: object
properties:
count:
type: integer
minimum: 0
description: Number of articles in this page.
required:
- count
description: Summary information about this response.
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- data
- has_more
- next_cursor
- meta
- request_id
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
description: Request exceeded the applicable rate limit.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: >-
News search failed because the index or an upstream resolver was
unavailable.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: []
components:
schemas:
NewsSearchEntityByName:
type: object
properties:
type:
type: string
enum:
- name
description: Use `name` to identify the company by name.
name:
type: string
minLength: 2
maxLength: 200
description: Company name.
required:
- type
- name
additionalProperties: false
description: Identify the company by name.
title: By Name
NewsSearchEntityByDomain:
type: object
properties:
type:
type: string
enum:
- domain
description: Use `domain` to identify the company by website domain.
domain:
type: string
minLength: 1
maxLength: 253
description: Company website domain, such as apple.com.
required:
- type
- domain
additionalProperties: false
description: Identify the company by website domain.
title: By Domain
NewsSearchEntityByTicker:
type: object
properties:
type:
type: string
enum:
- ticker
description: Use `ticker` to identify a publicly traded company.
ticker:
type: string
minLength: 1
maxLength: 20
pattern: ^[A-Za-z0-9.-]+$
description: Public-company ticker.
exchange:
type: string
enum:
- AMEX
- AMS
- AQS
- ASX
- ATH
- BER
- BME
- BRU
- BSE
- BUD
- BUE
- BVC
- CBOE
- CNQ
- CPH
- DFM
- DOH
- DUB
- DUS
- DXE
- EGX
- FSX
- HAM
- HEL
- HKSE
- HOSE
- ICE
- IOB
- IST
- JKT
- JNB
- JPX
- KLS
- KOE
- KSC
- KUW
- LIS
- LSE
- MCX
- MEX
- MIL
- MUN
- NASDAQ
- NEO
- NSE
- NYSE
- NZE
- OSL
- OTC
- PAR
- PNK
- PRA
- RIS
- SAO
- SAU
- SES
- SET
- SGO
- SHH
- SHZ
- SIX
- STO
- STU
- TAI
- TAL
- TLV
- TSX
- TSXV
- TWO
- VIE
- WSE
- XETRA
description: >-
Stock exchange the ticker trades on, used to disambiguate tickers
listed on multiple exchanges.
required:
- type
- ticker
additionalProperties: false
description: Identify the company by stock ticker, optionally scoped to an exchange.
title: By Ticker
NewsSearchEntityByIsin:
type: object
properties:
type:
type: string
enum:
- isin
description: Use `isin` to identify the company by its securities identifier.
isin:
type: string
pattern: ^[A-Za-z]{2}[A-Za-z0-9]{9}[0-9]$
description: International Securities Identification Number.
required:
- type
- isin
additionalProperties: false
description: Identify the company by International Securities Identification Number.
title: By ISIN
RequestTags:
type: array
items:
type: string
minLength: 1
maxLength: 50
maxItems: 20
description: Labels for filtering usage in the dashboard.
example:
- production
- team-alpha
KeyMetadata:
type: object
properties:
credits_consumed:
type: integer
description: Credits charged for this request.
credits_remaining:
type: integer
description: Credits remaining for your organization.
required:
- credits_consumed
- credits_remaining
description: Credits this request used and your remaining balance.
RequestId:
type: string
format: uuid
description: >-
Unique ID of this request, also in `X-Request-Id`. Include it when
contacting support.
example: 3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91
ErrorResponse:
type: object
properties:
message:
type: string
description: Human-readable error message.
error_code:
type: string
enum:
- INTERNAL_ERROR
- VALID
- NOT_FOUND
- FORBIDDEN
- USAGE_EXCEEDED
- RATE_LIMITED
- UNAUTHORIZED
- DISABLED
- PAID_PLAN_REQUIRED
- INSUFFICIENT_PERMISSIONS
- TIMEOUT_EXCEEDS_MAXIMUM
- TIMEOUT_TOO_SHORT_FOR_WAIT
- WEBSITE_ACCESS_ERROR
- WEBSITE_BLOCKED
- WEBSITE_NOT_FOUND
- PDF_SKIPPED
- PDF_IMAGES_ONLY
- INPUT_VALIDATION_ERROR
- ZDR_NOT_SUPPORTED
- ZDR_NOT_ENABLED
- FREE_EMAIL_DETECTED
- DISPOSABLE_EMAIL_DETECTED
- REQUEST_TIMEOUT
- COLD_DOMAIN_TIMEOUT_TOO_LOW
- UNSUPPORTED_CONTENT
- CONTENT_TOO_LARGE
- MONITOR_PAUSED
- MONITOR_NO_WEBHOOK
- COLLECTION_PAUSED
- MONITOR_LIMIT_EXCEEDED
- SEARCH_UNAVAILABLE
- BATCH_LIMIT_EXCEEDED
- BATCH_NOT_CANCELLABLE
- BATCH_NOT_COMPLETED
- IDEMPOTENCY_KEY_CONFLICT
- DELIVERY_IN_PROGRESS
- DELIVERY_ALREADY_DELIVERED
- DELIVERY_EXPIRED
- DELIVERY_CANCELLED
description: Machine-readable error code.
required_permission:
type: string
enum:
- logs:read
- data:execute
- monitors:read
- monitors:write
- batches:read
- batches:write
description: >-
Permission required for this request when error_code is
INSUFFICIENT_PERMISSIONS. Manage (write) also grants read access to
the same resource group.
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
headers:
RequestId:
description: Unique ID of this request; also `request_id` in JSON bodies.
schema:
type: string
format: uuid
RateLimitLimit:
description: >-
Maximum request units per minute, or maximum concurrent requests when
X-RateLimit-Mode is concurrency.
schema:
type: integer
minimum: 1
RateLimitRemaining:
description: >-
Request units remaining in the current minute, or concurrent requests
still available when X-RateLimit-Mode is concurrency.
schema:
type: integer
minimum: 0
RateLimitReset:
description: >-
Unix timestamp in seconds when the per-minute rate limit resets. Omitted
for concurrency limits.
schema:
type: integer
RateLimitMode:
description: >-
Set to concurrency when the organization is limited by concurrent
requests. Omitted for per-minute limits.
schema:
type: string
enum:
- concurrency
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
NotFound:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
X-RateLimit-Mode:
$ref: '#/components/headers/RateLimitMode'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Send `Authorization: Bearer `. Keys have full access unless
restricted to scopes.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.