Developers

The Stock Portfolio One API

Read your own portfolio data — portfolios, accounts, holdings, balances, a dividend calendar, recommendations, history, and support — over a simple, versioned JSON API. Read-only and strictly scoped to your account.

Quick start

The base URL is https://stockportfolio.one/api/v1. Three steps:

1. Generate a key on your API Keys page — you'll get a Client ID and a one-time Private Key.
2. Authenticate with HTTP Basic (Client ID = username, Private Key = password) over HTTPS.
3. Start at /portfolios and follow the ids downward.

curl -u ci_yourClientId:sk_yourPrivateKey \
  https://stockportfolio.one/api/v1/ping

{ "ok": true, "clientId": "ci_yourClientId", "serverTimeUtc": "2026-06-30T01:46:23Z" }

Authentication

Every request authenticates with HTTP Basic over HTTPS: your Client ID as the username and your Private Key as the password. The private key is shown only once when generated — store it securely; rotate it on the API Keys page if it's lost. Requests without valid credentials get 401 unauthorized. Every request is scoped to the key's owner; you can never reach another user's data.

Discovery

There's no master list of ids — you discover them by walking your own data top-down, and you only ever see what's yours:

1. GET /portfolios → returns your portfolios, each with an id.
2. GET /portfolios/{id}/accounts → accounts (with balances) in that portfolio, each with an id.
3. GET /accounts/{id}/holdings → holdings in that account, keyed by ticker.

A portfolio or account that isn't yours returns 404 — identical to one that doesn't exist, so the API never reveals that other ids are real.

Limits & headers

Your plan sets three independent limits, surfaced on every response:

• Rate — requests per minute. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix seconds). Over the limit → 429 with Retry-After.
• Quota — calls per calendar month (UTC). X-Quota-Limit, X-Quota-Remaining, X-Quota-Reset.
• Concurrency — simultaneous in-flight requests. Over the limit → 429.

Respect Retry-After and back off when you receive a 429.

Errors

Errors are JSON: { "error": "code", "message": "..." }. Common statuses:

Status	Meaning
200 / 201	Success / created.
400 bad_request	Invalid input (e.g. missing ticket subject/body).
401 unauthorized	Missing or invalid credentials.
403 insufficient_scope	Your plan's API scope doesn't include this endpoint.
404 not_found	No such resource, or it isn't yours.
429	rate_limited, quota_exceeded, or concurrency_exceeded — slow down.

Capabilities

All endpoints are GET unless noted, scoped to your account, and require the regular API scope — except Support, which requires full.

Portfolio

curl -u $CLIENT_ID:$PRIVATE_KEY https://stockportfolio.one/api/v1/portfolios

[ { "id": 5, "name": "My Portfolio", "source": "manual", "isPrimary": false, "accountCount": 7 } ]

Recommendations

Active suggestions and alerts, optionally narrowed by portfolio, account, or ticker.

curl -u $CLIENT_ID:$PRIVATE_KEY "https://stockportfolio.one/api/v1/recommendations?ticker=MKC"

Calendar

Upcoming dividend events for your holdings. Window defaults to the next 90 days; from/to override it (max 365-day span). Each event flags whether its ex-dividend / pay date is known or projected.

curl -u $CLIENT_ID:$PRIVATE_KEY "https://stockportfolio.one/api/v1/calendar?from=2026-07-01&to=2026-09-30"

History

Your real-portfolio audit trail, newest first (simulator activity excluded). limit defaults to 100, max 500.

Status

Platform health: overall site, financial-data feed, and API.

{ "site": "up", "financialData": "healthy", "api": "healthy", "serverTimeUtc": "..." }

Support (requires full scope)

List, view, open, and reply to your own support tickets.

curl -u $CLIENT_ID:$PRIVATE_KEY -X POST \
  -H "Content-Type: application/json" \
  -d '{"subject":"Question about dividends","body":"How are projected dates calculated?"}' \
  https://stockportfolio.one/api/v1/support/tickets

Interactive reference

The full machine-readable reference — every endpoint, parameter, and response schema, with a live "try it" console — is available to accounts with API access in their plan:

Open the interactive reference →

Don't have API access yet? See plans & pricing.