Building with TheProfitPath's API

OAuth connections

Register an app in Settings → Developer → OAuth apps in three steps: its name, website, and description (traders see the description on the approval screen); where it runs and its exact redirect URLs; and the most access it may ask for. Server apps receive a client secret; browser and native apps use a public client. Every authorization requires S256 PKCE and explicit consent, including server apps. After registering, the page shows the client ID, the one-time client secret, an example authorization URL, and the token request.

1. Generate a cryptographically random state (16–512 printable characters) and a PKCE verifier (43–128 characters). Store both with the pending login. Set code_challenge to the base64url SHA-256 digest of the verifier.
2. Redirect the user to /api/oauth/authorize with response_type=code, client_id, redirect_uri, space-separated scope, state, code_challenge, and code_challenge_method=S256. HTTPS redirects must match registration exactly; HTTP localhost is allowed for development.
3. The user signs in on TheProfitPath and allows or cancels. Verify the callback state and iss against your pending request and the discovered issuer. A cancellation returns error=access_denied.
4. Exchange the single-use code within five minutes using POST /api/oauth/token and application/x-www-form-urlencoded. Include grant_type=authorization_code, client_id, code, the identical redirect_uri, and code_verifier. Confidential clients also send their client secret using HTTP Basic authentication or client_secret in the body; use only one client authentication method.
5. Send the access_token as Authorization: Bearer. Tokens last up to 15 minutes. With read:me, GET /api/auth/me identifies the authorizing account. Use its stable id to associate that person with your app; email can change.
6. Refresh with grant_type=refresh_token, refresh_token, and the same client authentication. Save the new access and refresh tokens atomically. Serialize refreshes: reusing an old refresh token revokes the entire connection. Connections expire after 30 days and require fresh consent.

curl https://theprofitpath.app/api/oauth/token \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "code=$CODE" \
  --data-urlencode "redirect_uri=$REDIRECT_URI" \
  --data-urlencode "code_verifier=$CODE_VERIFIER"

Public clients omit client_secret. Browser requests use credentials: "omit"; CORS supports explicit developer credentials without sharing browser cookies. This is OAuth 2.0 authorization with an account identity endpoint; OpenID Connect ID tokens are not issued.

Disconnect in Connected apps, or POST /api/oauth/revoke with token and client authentication. Disabling a registered app revokes all its user connections. New consent replaces that user’s previous connection to the app. Revocation affects new requests immediately; an already-open news stream ends within 60 seconds.

Each registered app shows how many traders are connected and when the latest one connected; you never see who. From the app's ⋯ menu, Edit details and redirects changes the name, website, description, and redirect URLs: new sign-ins use them at once and existing connections stay. The app type and permissions stay as traders approved them; register a new app to change either. Rotate client secret (server apps) replaces the secret immediately: access tokens already issued keep working until they expire, but token refreshes need the new secret. Preview sign-in opens the real approval screen for your app with a fresh state and PKCE challenge; approving it connects your own account to the app, and the code it returns cannot be redeemed.

Discover endpoints and supported scopes at OAuth server metadata. Registration is managed through your signed-in Developer settings. Up to 10 active registered apps and 50 active connected apps are supported per account.

Complete exports

GET /api/trades?pagination=cursor&limit=200 returns items, hasMore, and nextCursor. Pass nextCursor as cursor on the next request and keep filters unchanged. Stop when nextCursor is null. This mode has no offset ceiling and avoids an expensive total count. Records are ordered by createdAt and then id, newest first.

let cursor;
do {
  const url = new URL("https://theprofitpath.app/api/trades");
  url.searchParams.set("pagination", "cursor");
  url.searchParams.set("limit", "200");
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, {
    headers: { "X-API-Key": process.env.TPP_API_KEY }
  });
  if (!response.ok) throw new Error(`Export failed: ${response.status}`);
  const page = await response.json();
  for (const trade of page.items) console.log(JSON.stringify(trade));
  cursor = page.nextCursor;
} while (cursor);

Trade responses retain journal notes, reviews, checklists, emotion phases, media links, and import-source availability. When hasImportSource is true, GET /api/trades/{id}/import-source retrieves the private original. Large sources provide revision, totalBytes, and chunkBytes: fetch each offset, decode the base64 data, join the bytes, verify SHA-256 against revision, and parse the JSON.

Default trade pagination still returns items and total, with limit 1–200 and offset 0–10,000. Cursor exports are a traversal of live data, not a snapshot: rerun to reconcile changes during export. updatedAt currently mirrors createdAt, so it cannot detect edits. Trashed trades use /trades/trash and remain restorable for 30 days.

Create trades with POST /trades and update supplied fields with PUT /trades/{id}. Use JSON numbers for numeric fields; use ISO 8601 or epoch milliseconds for times. Journal text fields accept up to 30,000 characters each. Account and strategy references must belong to the authorizing user. Consult OpenAPI for writable fields and aliases.

Updates preserve long notes and structured checklists without truncation. The images field accepts up to 12 Cloudinary HTTPS image or video URLs, each at most 2,048 characters, as an array or JSON-encoded array. Invalid or excess media returns 400 before saving.

Limits and errors

All API keys and OAuth connections for an account share 120 requests per minute across server instances. RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset describe that budget. Platform and endpoint limits also apply. JSON bodies are limited to 2 MiB. JSON responses over 1 KB are sent gzip or Brotli encoded when your client sends Accept-Encoding; most HTTP clients decode them automatically. OAuth refreshes are limited to 30 per connection per hour; reuse the access token until it approaches expiry.

• 400: invalid input, repeated query parameters, or malformed JSON. Correct the request.
• 401: invalid, revoked, or expired credential. Refresh an OAuth token once or reconnect; replace expired API keys.
• 403: missing scope, an unsupported developer operation, or account, plan, or platform restrictions. Wider scopes cannot enable browser-only operations.
• 404: missing resource or a resource you do not own. 409: conflict with current state.
• 413: request too large. Reduce the payload. 429: wait for Retry-After, then add jitter before retrying.
• 5xx: transient service failure (503 when the service is briefly busy, 502 or 504 when an upstream provider did not answer). Retry reads with a bounded backoff. Do not blindly retry creates or mutations: an interrupted response does not prove the write failed.

Developer-boundary errors include error, code, and requestId; keep X-Request-Id when reporting a failure. OAuth token errors follow the OAuth error and error_description format. A request rejected before the developer boundary may have a platform error format. Mutating operations do not currently offer an Idempotency-Key contract.