/api/v1/portfolio/portfolios/{portfolio_id}/briefs

Queue a portfolio brief

Queues a portfolio brief job for the requested portfolio snapshot.

Why use this

Start an asynchronous brief build and receive the job descriptor needed to poll the resulting brief.

Common use case

Create a portfolio briefing after a user selects an as-of timestamp and optional report sections.

Parameters

Name	In	Required	Default	Allowed	Description	Example
portfolio_id	path	required	—	—	Portfolio identifier.	00000000-0000-4000-8000-000000000004
as_of	body	optional	—	—	Optional canonical UTC timestamp ending in `Z`; accepts 0-6 fractional digits.	2026-09-07T12:00:00Z
sections	body	optional	—	—	Optional JSON array of up to 12 unique strings, each at most 60 characters. Omitted defaults to `[]`.	["performance","risk"]

Response schema

Field	Type	Nullable	Description
status	string	no	`success`.
request_id	string	no	Request correlation identifier.
timestamp	string	no	Response timestamp.
data	object	no	Queued job descriptor with `id`, `type` (`BRIEF`), `state`, `progress`, `errors`, `authority`, `created_at`, and `updated_at`.
data.authority	object	yes	Null until the job succeeds; a successful job carries `kind`, `reference`, `authoritative_version`, `reconciled_at`, and `evidence`.

Sample response

"status": "success"
"request_id": "00000000-0000-4000-8000-000000000010"
"timestamp": "2026-09-07T12:00:00Z"
"data":
- "id": "00000000-0000-4000-8000-000000000007"
- "type": "BRIEF"
- "state": "QUEUED"
- "progress":
- "errors": []
- "authority": null
- "created_at": "2026-09-07T12:00:00Z"
- "updated_at": "2026-09-07T12:00:00Z"
}

}

Errors

Status	Label	Description
202		Accepted; returns the queued `BRIEF` job descriptor in the success envelope.
400		`INVALID_REQUEST` — malformed or missing request input, including an invalid Idempotency-Key.
401		`UNAUTHENTICATED` — authentication is required.
403		`FORBIDDEN` — the caller lacks `portfolio:command:brief`.
404		`NOT_FOUND` — the portfolio does not exist or is not visible to the caller.
409		`CONFLICT` or `IDEMPOTENCY_KEY_REUSE_MISMATCH`.
422		`VALIDATION_FAILED` — the request shape or values are not valid.
429		`RATE_LIMITED` — retry after the server-provided delay.
503		`SERVICE_UNAVAILABLE`, `DEADLINE_EXCEEDED`, `RESULT_GRAPH_INVALID`, or `RESULT_GRAPH_LIMIT_EXCEEDED`.

Code samples

Reveal credentials

curl -X POST "https://api.finradar.ai/api/v1/portfolio/portfolios/00000000-0000-4000-8000-000000000004/briefs" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "as_of": "2026-09-07T12:00:00Z",
  "sections": "[\"performance\",\"risk\"]"
}'

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).