Quick Auth:
{" "}
Authenticate once to auto-fill your Bearer token across all API
endpoints
{modalMarkup}
;
}
## OpenAPI
````yaml openapi.json GET /v1/calendars/earnings
openapi: 3.0.3
info:
contact:
email: dev@aries.com
name: Aries Financial
description: >-
OpenAPI Specification for the Aries trading platform API.
# Authentication
Learn how to authenticate with the Aries API using OAuth2 and manage access
tokens in your SDK.
## Overview
The Aries API uses **OAuth2 with Bearer tokens** (JWT format) for
authentication. All API requests require a valid access token in the
`Authorization` header:
```
Authorization: Bearer
```
## Providing Client ID and Client Secret (SDK)
When using the generated SDK, provide your **Client ID** and **Client
Secret** when you create the API client (e.g. in the constructor or security
options). The SDK will use these to obtain and refresh the access token
internally; you do not need to manage tokens yourself.
Obtain your OAuth2 credentials from the Aries platform (e.g. Client Center /
Manage Account at https://app.aries.com):
- **Client ID** – Your application identifier (pass to SDK client)
- **Client Secret** – Your application secret key (pass to SDK client; use
PKCE for public clients where secret cannot be stored)
## Authentication Flow
### 1. Authorization Code Flow
For server-side or confidential clients:
1. **Redirect the user** to the authorization URL to sign in and consent:
- **URL:** `https://app.aries.com/oauth2/authorize`
- **Query params:** `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state`
2. **Exchange the code for tokens** (after user is redirected back with
`?code=.`):
- **POST** `https://api.aries.com/v1/oauth2/token`
- **Body:** `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `client_secret`
- Response includes `access_token` and `refresh_token`
3. **Call the API** with the access token: `Authorization: Bearer
`
### 2. PKCE Flow
For SPAs and mobile apps (public clients that cannot store `client_secret`):
1. Generate a **code_verifier** (random string) and **code_challenge** =
BASE64URL(SHA256(code_verifier)).
2. **Redirect the user** to `https://app.aries.com/oauth2/authorize` with
`code_challenge`, `code_challenge_method=S256`, plus `client_id`,
`redirect_uri`, `scope`, `state`.
3. **Exchange the code** at POST `https://api.aries.com/v1/oauth2/token`
with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`,
`code_verifier` (no client_secret).
4. Use the returned `access_token` as Bearer.
### 3. MFA Verification
If the user has MFA enabled, the authorize step may return `is_mfa: true`
and a `next_step_auth_id`. Call **POST**
`https://api.aries.com/v1/oauth2/authorize/mfa` with `next_step_auth_id` and
`verification_code` (6-digit code). Then continue with **POST**
`/v1/oauth2/authorize/confirm` to get the authorization code, and exchange
it at `/v1/oauth2/token`.
## Token Management
- **Refresh when expired:** POST `https://api.aries.com/v1/oauth2/token`
with `grant_type=refresh_token`, `client_id`, `client_secret`,
`refresh_token`.
- **Using a Bearer token directly:** If you already have an access token,
set the header `Authorization: Bearer ` on every request. The
SDK can accept a pre-obtained token and use it until it expires.
## OAuth2 Scopes
Request only the scopes your application needs. Available scopes:
| Scope | Description |
|-------|-------------|
| `user:information` | View user profile and personal details |
| `account:information` | View account balances, positions, and transaction
history |
| `order:execution` | Place, modify, and cancel orders |
| `order:information` | View order history and status |
| `position:information` | View current positions and holdings |
| `market:information` | Access live and historical market data |
| `calendar:information` | Access earnings, economic, and market schedule
data |
| `options:information` | Access options chains and expiration data |
| `analytics:information` | View analytics, ratings, and market insights |
| `market:supplemental` | News, company profiles, financials, filings, ETF
data, technical analysis |
Specify multiple scopes as a space-separated string, e.g.
`account:information order:execution market:information`.
## Security Best Practices
- **Store credentials securely** – Use environment variables or a secrets
manager for `client_id` and `client_secret`. Never hardcode them.
- **Handle token expiration** – Check for 401 responses and refresh the
token using the refresh_token, then retry the request.
- **Use HTTPS** – All authorization and token endpoints must be called over
HTTPS.
- **Validate state** – When using the authorization code flow, validate the
`state` parameter on the callback to prevent CSRF.
## Error Handling
- **400 Bad Request** – Invalid or missing parameters, validation failures,
or malformed JSON. Response bodies follow the same patterns as other errors
(flat `error` string, optional `codes`, nested `error` object, or rarely no
body).
- **401 Unauthorized** – Invalid or expired access token; refresh the token
or re-authenticate. JSON bodies are not identical on every route: you may
see a flat `error` string (sometimes with `codes`), a nested `error` object
(`type`, `code`, `message`), or rarely an empty body
- **403 Forbidden** – Insufficient scope or permissions for the requested
resource. Error JSON may be flat or nested, like 400/401.
- **404 Not Found** – Resource does not exist or is not visible. Error JSON
may be flat or nested.
- **429 Too Many Requests** – Rate limit exceeded; slow down and respect
`Retry-After` when the header is present. Error JSON may be flat or nested.
- **500 / 5xx** – Server or upstream failure; retry with backoff. Do not
depend on a single error JSON shape; some responses may have no body.
---
Endpoints in this spec: health, OAuth2 (authorize, confirm, mfa, token),
users, accounts, orders, market data, watchlist, chart, analytics,
calendars, company, economy, financials, indices, options, news, and
supplemental data.
title: Aries API — OpenAPI Specification
version: 1.0.0
servers:
- description: Production server
url: https://api.aries.com
security: []
tags:
- description: >-
Analytics endpoints for market data analysis including top gainers,
losers, volume leaders, sector analysis, analyst ratings, market breadth,
and net inflow
name: Analytics
- description: User management and profile endpoints
name: Users
- description: >-
Order management endpoints for placing, updating, canceling, and
previewing orders
name: Orders
- description: Account management endpoints for positions, orders, and balances
name: Accounts
- description: Calendar and mergers/acquisitions endpoints
name: Calendar
- description: >-
Market data endpoints for symbol search, real-time data access, and equity
details
name: Market Data
- description: >-
Watchlist endpoints for listing, creating, updating, and deleting
watchlists
name: Watchlist
- description: Chart endpoints for config, symbols, history, quotes, and server time
name: Chart
- description: News and news sentiment endpoints
name: News
- description: >-
Indices endpoints for groups, list, search, bar, bars, chart-bars,
realtime values
name: Indices
- description: Logos search and sync endpoints
name: Logos
- description: 'Corporate actions: spinoffs, tender offers, IPO calendar, dividends'
name: Corporate Actions
- description: 'Economy endpoints: inflation, inflation expectations, treasury yields'
name: Economy
- description: >-
Options endpoints: expiry dates, contracts, activity, trades, quotes,
unusual activity
name: Options
- description: >-
Financials: reported, statements, revenue breakdown, short volume, ratios,
short interest
name: Financials
- description: Signals and bull-bear cases
name: Signals
- name: Company
- name: ETF
- name: Filings
- name: Market
- name: Ownership
- name: Stocks
- name: Stock Estimates
- name: Stock Alternative
description: >-
Transcripts, company presentation, social sentiment, investment themes,
supply chain, and ESG data
- name: Technical Analysis
paths:
/v1/calendars/earnings:
get:
tags:
- Calendar
summary: Get Earnings Calendar
description: >-
Retrieve upcoming earnings release dates and historical earnings
announcement schedules for earnings season planning.
operationId: getEarningsCalendar
parameters:
- description: >-
Start date in YYYY-MM-DD format. Enter the first date to include in
the research window.
in: query
name: from
required: true
schema:
example: '2024-01-01'
format: date
type: string
- description: >-
End date in YYYY-MM-DD format. Enter the last date to include in the
research window.
in: query
name: to
required: true
schema:
example: '2024-01-31'
format: date
type: string
- description: >-
Optional stock symbol to filter results. If not provided, returns
earnings for all symbols.
in: query
name: symbol
schema:
example: AAPL
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetEarningsCalendarResponse'
examples:
success:
value:
- date: '2024-01-16'
symbol: AAPL
name: Apple Inc.
hour: amc
quarter: 1
year: 2024
epsActual: 2.18
epsEstimate: 2.1
epsSurprise: 0.08
revenueActual: 119580000000
revenueEstimate: 118000000000
revenueSurprise: 1580000000
marketCap: 2850000
logo:
logoLight: https://example.com/aapl-light.png
logoDark: https://example.com/aapl-dark.png
analystRating:
currentRating: Buy
priceTarget: 200.5
totalRatings: 45
successRate: 72%
averageReturn: 15.3%
description: Earnings calendar data retrieved successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- OAuth2:
- calendar:information
components:
schemas:
GetEarningsCalendarResponse:
description: >-
Array of earnings releases for the requested date range. Use it to show
upcoming or historical earnings events.
items:
$ref: '#/components/schemas/EarningRelease'
type: array
EarningRelease:
properties:
date:
description: Earnings release date
type: string
epsActual:
description: Actual earnings per share
nullable: true
type: number
epsEstimate:
description: Estimated earnings per share
nullable: true
type: number
hour:
description: >-
Time of day for earnings release: 'bmo' (before market open), 'amc'
(after market close), 'dmh' (during market hours)
type: string
quarter:
description: Quarter number (1-4)
type: integer
revenueActual:
description: Actual revenue
nullable: true
type: number
revenueEstimate:
description: Estimated revenue
nullable: true
type: number
symbol:
description: >-
Stock ticker symbol, such as AAPL. Use the exact ticker for the
company you want to research.
type: string
year:
description: Year of the earnings
type: integer
name:
description: Company name
type: string
epsSurprise:
description: Difference between actual and estimated EPS
nullable: true
type: number
revenueSurprise:
description: Difference between actual and estimated revenue
nullable: true
type: number
marketCap:
description: Market capitalization in millions
nullable: true
type: number
logo:
description: Company logos for UI display
type: object
properties:
logoLight:
description: Logo URL for light theme
type: string
logoDark:
description: Logo URL for dark theme
type: string
analystRating:
description: Analyst ratings summary
type: object
properties:
currentRating:
description: Current analyst rating (e.g., Buy, Sell, Hold)
type: string
priceTarget:
description: Average price target
type: number
totalRatings:
description: Total number of analyst ratings
type: integer
successRate:
description: Historical success rate of analysts
type: string
averageReturn:
description: Average return based on analyst recommendations
type: string
type: object
AuthenticationErrorEnvelope:
type: object
description: >-
JSON envelope where `error` is a nested object (`type`, `code`,
`message`, …). Many services use this shape for 400, 401, 403, 404, 429,
and 5xx when using the shared HTTP error format.
properties:
error:
$ref: '#/components/schemas/AuthenticationErrorDetail'
meta:
type: object
additionalProperties: true
description: Optional metadata
ErrorResponse:
properties:
codes:
description: Structured error codes for programmatic handling
items:
$ref: '#/components/schemas/ErrorCode'
type: array
error:
type: string
description: >-
Error detail as a string. Exact message content is not fixed and
should not be hard-coded.
example: string
metadata:
additionalProperties: true
description: Additional error context
type: object
type: object
AuthenticationErrorDetail:
type: object
description: >-
Structured payload for the nested `error` object. Services using the
shared Go error writer emit uppercase `type` values aligned with error
categories (for example `VALIDATION`, `BAD_REQUEST`, `AUTHENTICATION`,
`AUTHORIZATION`, `NOT_FOUND`, `RATE_LIMIT`, `INTERNAL`).
properties:
type:
type: string
description: >-
Error category emitted by the shared error writer, such as
VALIDATION, BAD_REQUEST, AUTHENTICATION, AUTHORIZATION, NOT_FOUND,
RATE_LIMIT, or INTERNAL.
example: AUTHENTICATION
code:
type: string
description: Machine-readable code
example: INVALID_TOKEN
message:
type: string
description: >-
Error detail as a string. Exact message content is not fixed and
should not be hard-coded.
example: string
details:
type: object
additionalProperties: true
description: Optional extra context
request_id:
type: string
description: Request correlation id when provided
ErrorCode:
properties:
code:
description: Machine-readable error code
example: INVALID_PASSWORD
type: string
description:
description: Human-readable description of the error
example: Password must be between 8 and 64 characters
type: string
field:
description: Field name that caused the error
example: password
type: string
type: object
responses:
BadRequest:
description: >-
Invalid query/path/body, malformed JSON, or failed validation.
**Backend (shared HTTP errors):** Routes that use the shared error
writer typically return a **nested** JSON object: `error.type` is an
uppercase category such as `VALIDATION` or `BAD_REQUEST` (see the API
implementation). Other routes may return the **flat** `ErrorResponse`
shape (`error` as a string, optional `codes`). The body may rarely be
empty.
**OpenAPI:** Every operation’s **400** response references this
component so the documented schema and examples stay aligned.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
- $ref: '#/components/schemas/ErrorResponse'
description: >-
400 responses commonly use a nested `error` object (`type`,
`code`, `message`, optional `details`). Some services still return
flat `ErrorResponse` (`error` string, optional `codes`).
examples:
nested_shared_http_error:
summary: Nested error (typical for shared WriteHTTPError-style responses)
value:
error:
type: VALIDATION
code: VALIDATION_ERROR
message: Query parameter validation failed
details:
fieldName: field is required
nested_bad_request:
summary: Nested error (BAD_REQUEST / invalid JSON)
value:
error:
type: BAD_REQUEST
code: INVALID_JSON
message: string
flat_string:
summary: Flat error string
value:
error: string
flat_with_codes:
summary: Flat error with field codes (some services)
value:
error: string
codes:
- field: string
code: string
description: string
Unauthorized:
description: >-
Authentication failed: missing credentials, invalid JWT, or expired
access token.
**Response body variants:** Some routes return JSON with a string
`error` field (and optionally `codes` / `metadata`). Others return JSON
where `error` is a structured object (`type`, `code`, `message`, and
optionally `details`, `request_id`). In edge cases (for example certain
gateway or middleware paths) the response may have **no body** even
though the status is 401—clients should treat 401 as unauthenticated and
refresh or re-authenticate regardless of body shape.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorResponse'
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
description: >-
401 responses may use a flat `ErrorResponse` shape or a nested
`error` object. Inspect `error`: if it is a string, use the flat
shape; if it is an object, use the structured shape.
examples:
flat_message:
summary: Flat error string (typical)
value:
error: string
flat_with_codes:
summary: Flat error with structured codes
value:
error: string
codes:
- code: string
description: string
nested_error_object:
summary: Nested error (shared HTTP error format)
value:
error:
type: AUTHENTICATION
code: INVALID_TOKEN
message: string
Forbidden:
description: >-
Authenticated but not allowed to perform this action or access this
resource (insufficient scope or role).
**Response body variants:** Flat `ErrorResponse` or nested `error`
object, same pattern as 400/401.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorResponse'
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
description: 403 responses may use a flat or nested error shape.
examples:
flat:
summary: Flat message
value:
error: string
nested:
summary: Nested error (shared HTTP error format)
value:
error:
type: AUTHORIZATION
code: INSUFFICIENT_SCOPE
message: string
NotFound:
description: >-
The requested resource does not exist or is not visible to this caller.
**Response body variants:** Flat `ErrorResponse` or nested `error`
object.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorResponse'
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
description: 404 responses may use a flat or nested error shape.
examples:
flat:
summary: Flat message
value:
error: string
nested:
summary: Nested error (shared HTTP error format)
value:
error:
type: NOT_FOUND
code: RESOURCE_NOT_FOUND
message: string
InternalServerError:
description: >-
Unexpected server error or upstream failure. **Retry with exponential
backoff**; do not assume a specific JSON body shape.
**Response body variants:** Flat `ErrorResponse`, nested `error` object,
or occasionally a minimal message. Some paths may return **no body**.
content:
application/json:
examples:
flat_string:
summary: Flat error string
value:
error: string
nested_error_object:
summary: Nested error (shared HTTP error format)
value:
error:
type: INTERNAL
code: INTERNAL_ERROR
message: string
schema:
oneOf:
- $ref: '#/components/schemas/ErrorResponse'
- $ref: '#/components/schemas/AuthenticationErrorEnvelope'
description: 5xx responses may use a flat or nested error shape.
securitySchemes:
OAuth2:
type: oauth2
description: >-
OAuth2 Bearer token: obtain an access token from the token endpoint and
send it in the Authorization header.
flows:
clientCredentials:
tokenUrl: https://api.aries.com/v1/oauth2/token
refreshUrl: https://api.aries.com/v1/oauth2/token
scopes:
user:information: View user profile and personal details
account:information: View account balances, positions, and transaction history
order:execution: Place, modify, and cancel orders
order:information: View order history and status
position:information: View current positions and holdings
market:information: Access live and historical market data
calendar:information: Access earnings, economic, and market schedule data
options:information: Access options chains and expiration data
analytics:information: View analytics, ratings, and market insights
market:supplemental: >-
News, company profiles, financials, filings, ETF data, technical
analysis
user:management: >-
Manage user-scoped resources such as watchlists and other saved
configuration.
authorizationCode:
authorizationUrl: https://app.aries.com/oauth2/authorize
tokenUrl: https://api.aries.com/v1/oauth2/token
refreshUrl: https://api.aries.com/v1/oauth2/token
scopes:
user:information: View user profile and personal details
account:information: View account balances, positions, and transaction history
order:execution: Place, modify, and cancel orders
order:information: View order history and status
position:information: View current positions and holdings
market:information: Access live and historical market data
calendar:information: Access earnings, economic, and market schedule data
options:information: Access options chains and expiration data
analytics:information: View analytics, ratings, and market insights
market:supplemental: >-
News, company profiles, financials, filings, ETF data, technical
analysis
user:management: >-
Manage user-scoped resources such as watchlists and other saved
configuration.
````