AlphaSense Watchlist API
Create, read, update, and delete user watchlists - persisted bundles of companies, tickers, and saved searches that drive personalized alerts, digests, and re-ranked Search results.
OpenAPI Specification
openapi: 3.1.0
info:
title: AlphaSense Utility APIs
description: >-
AlphaSense's GraphQL-fronted Utility APIs covering Search, Companies,
Brokers, Watchlist, Trends, User, Download / Export, and the REST
Ingestion API used by Enterprise Intelligence customers. All GraphQL
surfaces share the single /gql endpoint at api.alpha-sense.com and the
same OAuth 2.0 + x-api-key authentication as the Agent API; the Ingestion
API is REST under /services/i/ingestion-api/v1/. Documented at
https://developer.alpha-sense.com/api/getting-started.
version: '1.0'
contact:
name: AlphaSense Developer Support
url: https://developer.alpha-sense.com/
termsOfService: https://www.alpha-sense.com/legal/
externalDocs:
description: AlphaSense API Getting Started
url: https://developer.alpha-sense.com/api/getting-started
servers:
- url: https://api.alpha-sense.com
description: AlphaSense SaaS API gateway
- url: https://{customerDomain}
description: AlphaSense Private Cloud (customer-hosted)
variables:
customerDomain:
default: customer.alpha-sense.cloud
tags:
- name: Search
description: Document search across the AlphaSense corpus (500M+ documents).
- name: Companies
description: Company entity resolution and metadata.
- name: Brokers
description: Broker research firm reference data (1,500+ firms).
- name: Watchlist
description: User watchlist CRUD operations.
- name: Trends
description: Keyword and theme frequency over time.
- name: User
description: User profile and entitlement operations.
- name: Download
description: Bulk document and report export.
- name: Ingestion
description: Push customer-owned content into Enterprise Intelligence.
security:
- bearerAuth: []
apiKeyHeader: []
paths:
/gql:
post:
operationId: utilityGraphqlGateway
summary: Execute An AlphaSense Utility GraphQL Operation
description: >-
Same /gql endpoint as the Agent API; pick the Utility surface via the
GraphQL operation name (`search`, `companies`, `brokers`, `watchlists`,
`trends`, `user`, `downloads`).
tags:
- Search
- Companies
- Brokers
- Watchlist
- Trends
- User
- Download
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLRequest'
responses:
'200':
description: GraphQL response envelope.
content:
application/json:
schema:
$ref: '#/components/schemas/GraphQLResponse'
'401':
description: Missing or invalid bearer token / API key.
'429':
description: Rate or credit limit exceeded.
/services/i/ingestion-api/v1/documents:
post:
operationId: ingestDocument
summary: Ingest A Customer Document Into Enterprise Intelligence
description: >-
REST endpoint for pushing customer-owned documents (board decks, CRM
exports, meeting transcripts, research notes) into AlphaSense
Enterprise Intelligence so they become searchable alongside the
external AlphaSense corpus.
tags:
- Ingestion
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IngestionDocumentRequest'
responses:
'202':
description: Document accepted for ingestion.
content:
application/json:
schema:
$ref: '#/components/schemas/IngestionJob'
'400':
description: Validation failed.
'401':
description: Missing or invalid bearer token / API key.
/services/i/ingestion-api/v1/jobs/{jobId}:
get:
operationId: getIngestionJob
summary: Get The Status Of An Ingestion Job
description: >-
Retrieve the processing state and document identifier of an ingestion
job previously submitted via POST /services/i/ingestion-api/v1/documents.
tags:
- Ingestion
parameters:
- name: jobId
in: path
required: true
schema:
type: string
responses:
'200':
description: Ingestion job state.
content:
application/json:
schema:
$ref: '#/components/schemas/IngestionJob'
'404':
description: Job not found.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
apiKeyHeader:
type: apiKey
in: header
name: x-api-key
schemas:
GraphQLRequest:
type: object
required:
- query
properties:
query:
type: string
variables:
type: object
additionalProperties: true
operationName:
type: string
GraphQLResponse:
type: object
properties:
data:
type: object
additionalProperties: true
errors:
type: array
items:
$ref: '#/components/schemas/GraphQLError'
GraphQLError:
type: object
properties:
message:
type: string
path:
type: array
items:
type: string
extensions:
type: object
additionalProperties: true
Document:
type: object
properties:
id:
type: string
title:
type: string
releasedAt:
type: string
format: date-time
sourceType:
type: string
description: One of filing, broker, transcript, tegus, news, internal.
companies:
type: array
items:
type: string
url:
type: string
format: uri
Company:
type: object
properties:
id:
type: string
name:
type: string
ticker:
type: string
cik:
type: string
isin:
type: string
sector:
type: string
industry:
type: string
Broker:
type: object
properties:
id:
type: string
name:
type: string
country:
type: string
coverage:
type: array
items:
type: string
Watchlist:
type: object
properties:
id:
type: string
name:
type: string
items:
type: array
items:
type: object
properties:
type:
type: string
enum: [company, ticker, query]
value:
type: string
TrendPoint:
type: object
properties:
date:
type: string
format: date
value:
type: number
keyword:
type: string
User:
type: object
properties:
id:
type: string
email:
type: string
format: email
name:
type: string
entitlements:
type: array
items:
type: string
DownloadJob:
type: object
properties:
id:
type: string
status:
type: string
enum: [queued, running, ready, failed]
url:
type: string
format: uri
expiresAt:
type: string
format: date-time
IngestionDocumentRequest:
type: object
required:
- title
- mimeType
- content
properties:
title:
type: string
mimeType:
type: string
description: MIME type of the uploaded document.
content:
type: string
description: Base64-encoded document content or a presigned upload reference.
tags:
type: array
items:
type: string
sourceType:
type: string
enum: [internal]
IngestionJob:
type: object
properties:
id:
type: string
status:
type: string
enum: [accepted, processing, ready, failed]
documentId:
type: string
description: AlphaSense document id once ingestion completes.
message:
type: string