Linkwiz API · v1

Endpoint reference

Methods, parameters and response schemas from the downloadable OpenAPI contract.

Download OpenAPI 1.1.0-rc.1. All paths below are relative to https://app.linkwiz.ai/api/v1. Every endpoint requires a bearer key. Report/profile IDs are UUIDs; insight, evidence and revision IDs are opaque strings.

Method	Path	Purpose
GET	`/context`	Read the calling key's workspace and permissions
GET	`/workspace`	Read the bound workspace
GET	`/reports`	List workspace reports
POST	`/reports`	Create a report and queue supplied profiles
GET	`/reports/{report_id}`	Read one report
GET	`/reports/{report_id}/profiles`	List active personal profile attachments
GET	`/reports/{report_id}/scans/{scan_run_id}`	Read scan status and counts
POST	`/reports/{report_id}/profile-imports`	Validate or add people to an existing report
GET	`/reports/{report_id}/profile-imports/{import_id}`	Recover a saved import receipt
GET	`/reports/{report_id}/analysis`	Report readiness and existing analysis summary
GET	`/reports/{report_id}/analysis/profiles`	Current profile checks and evidence references
GET	`/reports/{report_id}/analysis/activity`	Eligible stored activity evidence
GET	`/reports/{report_id}/analysis/evidence/{evidence_id}`	Authenticated screenshot download (approved scope, A3 implementation)

Pagination and responses

Successful responses contain data and request_id. List responses also contain page.next_cursor; stop when it is null. Pass the returned cursor unchanged with the same endpoint and filters. Lists default to 50 items, up to 100. Report lists exclude archived reports unless include_archived=true.

Report reads return company information, profile counts, analysis availability and report URLs. Profile reads return the roster, names, titles, headlines, LinkedIn URLs and analysis availability. Charts and exports remain in the report UI.

Analysis reads expose stored checks, recommendations, activity and eligible screenshots. Analysis pages use top-level revision and next_cursor. Profiles default to 10/max 25; activity defaults to 25/max 100. Follow the cursor even when a page is shorter than the limit. See readiness and polling semantics.

GET`/context`

Read the calling key's workspace and permissions

Required permissions: workspace:read.

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

getContext 200 schema

{
  "$ref": "#/components/schemas/ContextResponse"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

getContext 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

getContext 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Access denied: forbidden, platform_api_not_included, platform_subscription_or_trial_required, or email_verification_required as applicable. retryable=false; follow next_action before resubmitting.

getContext 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

getContext 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Temporary request rate limit. retryable=true; wait Retry-After seconds before a bounded retry with the same write idempotency key and body.

getContext 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

Unexpected server failure. Safe internal_error response with request_id; retryable=true permits bounded backoff with the same write idempotency key and body. Contact support with request_id if persistent.

getContext 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

API access paused, disabled or not configured. unavailable with retryable=false; check workspace configuration or contact support with request_id.

getContext 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/workspace`

Read the bound workspace

Required permissions: workspace:read.

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

getWorkspace 200 schema

{
  "$ref": "#/components/schemas/WorkspaceResponse"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Access denied: forbidden, platform_api_not_included, platform_subscription_or_trial_required, or email_verification_required as applicable. retryable=false; follow next_action before resubmitting.

getWorkspace 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

getWorkspace 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Temporary request rate limit. retryable=true; wait Retry-After seconds before a bounded retry with the same write idempotency key and body.

getWorkspace 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

getWorkspace 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

API access paused, disabled or not configured. unavailable with retryable=false; check workspace configuration or contact support with request_id.

getWorkspace 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports`

List workspace reports

Required permissions: reports:read.

Parameter	Location	Required	Value
`limit`	query	No	{"type":"integer","minimum":1,"maximum":100,"default":50}
`cursor`	query	No	Signed opaque cursor bound to workspace, route, filters and the first-page upper watermark. Invalid or changed bindings return 400.
`company_root_domain`	query	No	Hostname or HTTP(S) company URL. Normalized using public and private suffix rules; matches the root and its subdomains.
`include_archived`	query	No	{"type":"boolean","default":false}

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

listReports 200 schema

{
  "$ref": "#/components/schemas/ReportCollection"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

listReports 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

listReports 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Access denied: forbidden, platform_api_not_included, platform_subscription_or_trial_required, or email_verification_required as applicable. retryable=false; follow next_action before resubmitting.

listReports 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

listReports 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Temporary request rate limit. retryable=true; wait Retry-After seconds before a bounded retry with the same write idempotency key and body.

listReports 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

listReports 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

API access paused, disabled or not configured. unavailable with retryable=false; check workspace configuration or contact support with request_id.

listReports 503 schema

{
  "$ref": "#/components/schemas/Error"
}

POST`/reports`

Create a report and queue supplied profiles

JSON only; maximum 1 MiB and 100 people. All rows validate before mutation. Unknown fields rejected. Duplicates keep the first occurrence. Empty reports queue no scans; populated reports queue full_profile for people and activity for people plus the company page. No external lookup occurs during creation. Default create permits separate reports for one company. return_existing returns workspace matches across all states without adding supplied people. Separate idempotency keys represent separate intents. If initial scan authorization fails, the entire operation rolls back: no new report, profile additions/restorations, scans or successful receipt are saved. Correct the account access before retrying; subscription eligibility rules are unchanged.

Required permissions: reports:create, reports:read.

Parameter	Location	Required	Value
`Idempotency-Key`	header	Yes	{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,128}$"}

JSON request schema

createReport request schema

{
  "$ref": "#/components/schemas/CreateReport"
}

Response codes and schemas

HTTP 200

All matching report references, capped at 100. Follow next_cursor through GET /reports?company_root_domain=...&include_archived=true. Supplied profiles are not added and no scans start.

createReport 200 schema

{
  "$ref": "#/components/schemas/ExistingReportsResponse"
}

HTTP 201

Report and queue records committed atomically. Location points to report GET. Scan completion is asynchronous.

createReport 201 schema

{
  "$ref": "#/components/schemas/CreatedReportResponse"
}

HTTP 400

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Access denied: forbidden, platform_api_not_included, platform_subscription_or_trial_required, or email_verification_required as applicable. retryable=false; follow next_action before resubmitting.

createReport 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 409

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key. Platform access, capacity and scan allowance conflicts are not automatically retryable; follow error.next_action.

createReport 409 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 413

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 413 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 415

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 415 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 422

Redacted JSON error. For 429 honor Retry-After; for an uncertain result retry the same body and Idempotency-Key.

createReport 422 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Temporary request rate limit. retryable=true; wait Retry-After seconds before a bounded retry with the same write idempotency key and body.

createReport 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

createReport 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

API access paused, disabled or not configured. unavailable with retryable=false; check workspace configuration or contact support with request_id.

createReport 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports/{report_id}`

Read one report

Required permissions: reports:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

getReport 200 schema

{
  "$ref": "#/components/schemas/ReportResponse"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

getReport 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

getReport 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Access denied: forbidden, platform_api_not_included, platform_subscription_or_trial_required, or email_verification_required as applicable. retryable=false; follow next_action before resubmitting.

getReport 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

getReport 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Temporary request rate limit. retryable=true; wait Retry-After seconds before a bounded retry with the same write idempotency key and body.

getReport 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

getReport 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

API access paused, disabled or not configured. unavailable with retryable=false; check workspace configuration or contact support with request_id.

getReport 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports/{report_id}/profiles`

List active personal profile attachments

Required permissions: profiles:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`limit`	query	No	{"type":"integer","minimum":1,"maximum":100,"default":50}
`cursor`	query	No	Signed opaque cursor bound to workspace, route, filters and the first-page upper watermark. Invalid or changed bindings return 400.

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

listReportProfiles 200 schema

{
  "$ref": "#/components/schemas/ProfileCollection"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Access denied: forbidden, platform_api_not_included, platform_subscription_or_trial_required, or email_verification_required as applicable. retryable=false; follow next_action before resubmitting.

listReportProfiles 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

listReportProfiles 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Temporary request rate limit. retryable=true; wait Retry-After seconds before a bounded retry with the same write idempotency key and body.

listReportProfiles 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

listReportProfiles 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

API access paused, disabled or not configured. unavailable with retryable=false; check workspace configuration or contact support with request_id.

listReportProfiles 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports/{report_id}/scans/{scan_run_id}`

Read scan status and counts

Required permissions: reports:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`scan_run_id`	path	Yes	{"type":"string","format":"uuid"}

Response codes and schemas

HTTP 200

Success. Cache-Control: no-store; X-Request-ID matches request_id.

getReportScan 200 schema

{
  "$ref": "#/components/schemas/ScanResponse"
}

HTTP 400

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Access denied: forbidden, platform_api_not_included, platform_subscription_or_trial_required, or email_verification_required as applicable. retryable=false; follow next_action before resubmitting.

getReportScan 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

JSON error. No token, raw database error or submitted value is echoed.

getReportScan 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Temporary request rate limit. retryable=true; wait Retry-After seconds before a bounded retry with the same write idempotency key and body.

getReportScan 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

getReportScan 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

API access paused, disabled or not configured. unavailable with retryable=false; check workspace configuration or contact support with request_id.

getReportScan 503 schema

{
  "$ref": "#/components/schemas/Error"
}

POST`/reports/{report_id}/profile-imports`

Validate or add people to an existing report

JSON only, 1–100 people, at most 1 MiB. Whole-batch validation. validation_only=true creates no roster changes, receipt, retry reservation or scans, but counts against request admission. Commit rechecks current state. Added/restored people queue full-profile and activity jobs; duplicates queue nothing. Removed people are restored with a note and preserved details/history. Receipts omit supplied names and URLs. Idempotency-Key is required for commits, scoped to workspace, operation and report; same normalized ordered body replays the saved receipt for 30 days, different body returns 409. Existing archived reports return 409. Shares configurable write limits with report creation. Default ceilings: 10 requests/key/minute, 50/workspace/minute and 1000 submitted rows/workspace/minute; workspace settings may differ. If initial scan authorization fails, the entire operation rolls back: no new report, profile additions/restorations, scans or successful receipt are saved. Correct the account access before retrying; subscription eligibility rules are unchanged.

Required permissions: reports:read, profiles:add.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`validation_only`	query	No	{"type":"boolean","default":false}
`Idempotency-Key`	header	No	Required unless validation_only=true. Use a new key for each intended commit; reuse it only to recover that request.

JSON request schema

importProfiles request schema

{
  "$ref": "#/components/schemas/ProfileImport"
}

Response codes and schemas

HTTP 200

Preview only; state may change before commit.

importProfiles 200 schema

{
  "$ref": "#/components/schemas/ImportValidationResponse"
}

HTTP 201

Import committed or saved receipt replayed. Scan status is a separate read.

importProfiles 201 schema

{
  "$ref": "#/components/schemas/ImportReceiptResponse"
}

HTTP 400

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Access denied: forbidden, platform_api_not_included, platform_subscription_or_trial_required, or email_verification_required as applicable. retryable=false; follow next_action before resubmitting.

importProfiles 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 409

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed. Platform access, capacity and scan allowance conflicts are not automatically retryable; follow error.next_action.

importProfiles 409 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 413

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 413 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 415

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 415 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 422

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

importProfiles 422 schema

{
  "$ref": "#/components/schemas/ImportValidationError"
}

HTTP 429

Temporary request rate limit. retryable=true; wait Retry-After seconds before a bounded retry with the same write idempotency key and body.

importProfiles 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

importProfiles 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

API access paused, disabled or not configured. unavailable with retryable=false; check workspace configuration or contact support with request_id.

importProfiles 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports/{report_id}/profile-imports/{import_id}`

Recover a saved import receipt

Requires current access; receipt contents are immutable and are not live scan status. Known authorized receipts expire after 30 days (410); wrong report/workspace or unknown receipt returns 404. Shares read limits: 60 requests/key/minute and 300/workspace/minute.

Required permissions: imports:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`import_id`	path	Yes	{"type":"string","format":"uuid"}

Response codes and schemas

HTTP 200

Saved receipt.

getProfileImport 200 schema

{
  "$ref": "#/components/schemas/ImportReceiptResponse"
}

HTTP 400

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 400 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 401

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 401 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 403

Access denied: forbidden, platform_api_not_included, platform_subscription_or_trial_required, or email_verification_required as applicable. retryable=false; follow next_action before resubmitting.

getProfileImport 403 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 404

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 404 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 410

No-store JSON error with X-Request-ID. No supplied personal values, keys or internal database errors are echoed.

getProfileImport 410 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 429

Temporary request rate limit. retryable=true; wait Retry-After seconds before a bounded retry with the same write idempotency key and body.

getProfileImport 429 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 500

getProfileImport 500 schema

{
  "$ref": "#/components/schemas/Error"
}

HTTP 503

API access paused, disabled or not configured. unavailable with retryable=false; check workspace configuration or contact support with request_id.

getProfileImport 503 schema

{
  "$ref": "#/components/schemas/Error"
}

GET`/reports/{report_id}/analysis`

Report readiness and existing analysis summary

Read existing finalized results within the calling workspace. Requires enabled analysis access and the permissions below. Reads do not initiate scans or AI generation. See /developers/guides/analysis-results for readiness, freshness and reconciliation semantics.

Required permissions: reports:read, analysis:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`as_of`	query	No	Optional UTC/offset observation cutoff for profile analysis. Monthly views use the last instant of the selected month in period.timezone. Previous-month comparison, per-profile observation IDs, roster membership and freshness are returned. Activity remains independently filtered. Bind the same cutoff to all pages and evidence reads. Omit for current month to date. History entitlements apply.

Response codes and schemas

HTTP 200

Current authorized results. Empty/not-ready is a successful response.

getReportAnalysis 200 schema

{
  "$ref": "#/components/schemas/AnalysisSummaryResponse"
}

HTTP 400

Invalid request or cursor. Correct input or restart expired pagination.

getReportAnalysis 400 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 401

Invalid or inactive key; do not automatically retry.

getReportAnalysis 401 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 403

Current authorization, scope or API entitlement denied.

getReportAnalysis 403 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 404

Not found in authorized report, or eligible evidence unavailable.

getReportAnalysis 404 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 405

Method not allowed.

getReportAnalysis 405 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 429

Rate limit; honor Retry-After and backoff.

getReportAnalysis 429 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 500

Unexpected failure; bounded retries, then contact support with request_id.

getReportAnalysis 500 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 503

API or extension disabled/unavailable; check configuration before retrying.

getReportAnalysis 503 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

GET`/reports/{report_id}/analysis/profiles`

Current profile checks and evidence references

Required permissions: reports:read, profiles:read, analysis:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`limit`	query	No	Maximum items in this page.
`cursor`	query	No	Opaque signed continuation; binds report, workspace, all filters and collection revision; expires in 15 minutes.
`expected_revision`	query	No	Reject with results_changed if this collection revision is no longer current.
`profile_id`	query	No	Optional current report attachment. Foreign, removed or unknown attachments return scoped 404.
`as_of`	query	No	Optional UTC/offset observation cutoff for profile analysis. Monthly views use the last instant of the selected month in period.timezone. Previous-month comparison, per-profile observation IDs, roster membership and freshness are returned. Activity remains independently filtered. Bind the same cutoff to all pages and evidence reads. Omit for current month to date. History entitlements apply.

Response codes and schemas

HTTP 200

Current authorized results. Empty/not-ready is a successful response.

listProfileAnalysis 200 schema

{
  "$ref": "#/components/schemas/AnalysisProfilePage"
}

HTTP 400

Invalid request or cursor. Correct input or restart expired pagination.

listProfileAnalysis 400 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 401

Invalid or inactive key; do not automatically retry.

listProfileAnalysis 401 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 403

Current authorization, scope or API entitlement denied.

listProfileAnalysis 403 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 404

Not found in authorized report, or eligible evidence unavailable.

listProfileAnalysis 404 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 405

Method not allowed.

listProfileAnalysis 405 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 409

results_changed: bounded restart of the collection; do not commit partial reconciliation.

listProfileAnalysis 409 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 422

A single stored record exceeds the supported response bound. result_too_large is non-retryable; contact support with request_id.

listProfileAnalysis 422 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 429

Rate limit; honor Retry-After and backoff.

listProfileAnalysis 429 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 500

Unexpected failure; bounded retries, then contact support with request_id.

listProfileAnalysis 500 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 503

API or extension disabled/unavailable; check configuration before retrying.

listProfileAnalysis 503 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

GET`/reports/{report_id}/analysis/activity`

Eligible stored activity evidence

Required permissions: reports:read, profiles:read, analysis:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`limit`	query	No	Maximum items in this page.
`cursor`	query	No	Opaque signed continuation; binds report, workspace, all filters and collection revision; expires in 15 minutes.
`expected_revision`	query	No	Reject with results_changed if this collection revision is no longer current.
`profile_id`	query	No	Optional current report attachment. Foreign, removed or unknown attachments return scoped 404.
`event_type`	query	No	Single event type.
`occurred_from`	query	No	Inclusive source event timestamp; excludes unknown dates.
`occurred_to`	query	No	Exclusive source event timestamp; excludes unknown dates.

Response codes and schemas

HTTP 200

Current authorized results. Empty/not-ready is a successful response.

listAnalysisActivity 200 schema

{
  "$ref": "#/components/schemas/AnalysisActivityPage"
}

HTTP 400

Invalid request or cursor. Correct input or restart expired pagination.

listAnalysisActivity 400 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 401

Invalid or inactive key; do not automatically retry.

listAnalysisActivity 401 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 403

Current authorization, scope or API entitlement denied.

listAnalysisActivity 403 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 404

Not found in authorized report, or eligible evidence unavailable.

listAnalysisActivity 404 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 405

Method not allowed.

listAnalysisActivity 405 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 409

results_changed: bounded restart of the collection; do not commit partial reconciliation.

listAnalysisActivity 409 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 422

A single stored record exceeds the supported response bound. result_too_large is non-retryable; contact support with request_id.

listAnalysisActivity 422 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 429

Rate limit; honor Retry-After and backoff.

listAnalysisActivity 429 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 500

Unexpected failure; bounded retries, then contact support with request_id.

listAnalysisActivity 500 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 503

API or extension disabled/unavailable; check configuration before retrying.

listAnalysisActivity 503 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

GET`/reports/{report_id}/analysis/evidence/{evidence_id}`

Authenticated screenshot download (approved scope, A3 implementation)

Required permissions: reports:read, profiles:read, analysis:read.

Parameter	Location	Required	Value
`report_id`	path	Yes	{"type":"string","format":"uuid"}
`evidence_id`	path	Yes	{"type":"string","pattern":"^ev_[a-f0-9]{64}$"}
`as_of`	query	No	Optional UTC/offset observation cutoff for profile analysis. Monthly views use the last instant of the selected month in period.timezone. Previous-month comparison, per-profile observation IDs, roster membership and freshness are returned. Activity remains independently filtered. Bind the same cutoff to all pages and evidence reads. Omit for current month to date. History entitlements apply.

Response codes and schemas

HTTP 200

Authenticated evidence bytes, subject to 10 MiB bound.

HTTP 400

Invalid request or cursor. Correct input or restart expired pagination.

downloadAnalysisEvidence 400 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 401

Invalid or inactive key; do not automatically retry.

downloadAnalysisEvidence 401 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 403

Current authorization, scope or API entitlement denied.

downloadAnalysisEvidence 403 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 404

Not found in authorized report, or eligible evidence unavailable.

downloadAnalysisEvidence 404 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 405

Method not allowed.

downloadAnalysisEvidence 405 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 429

Rate limit; honor Retry-After and backoff.

downloadAnalysisEvidence 429 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 500

Unexpected failure; bounded retries, then contact support with request_id.

downloadAnalysisEvidence 500 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

HTTP 503

API or extension disabled/unavailable; check configuration before retrying.

downloadAnalysisEvidence 503 schema

{
  "$ref": "#/components/schemas/AnalysisError"
}

Schema definitions

A $ref points to a definition below and in the OpenAPI download. Expand a definition to see required fields, types and allowed values.

Error

Error schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean",
          "description": "Whether an automatic retry without correcting the account or request could help. Not a guarantee of success; use bounded backoff. False for account, permission, input, capacity and configuration failures."
        },
        "next_action": {
          "type": "string",
          "description": "Safe user-facing guidance for correcting the cause or retrying. Automate using code and retryable, not by parsing this text."
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "next_action"
      ],
      "additionalProperties": false
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "error",
    "request_id"
  ],
  "additionalProperties": false
}

Context

Context schema

{
  "type": "object",
  "properties": {
    "key_id": {
      "type": "string",
      "format": "uuid"
    },
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "workspace_id": {
      "type": "string",
      "format": "uuid"
    },
    "scopes": {
      "type": "array",
      "items": {
        "enum": [
          "*",
          "workspace:read",
          "reports:read",
          "profiles:read",
          "reports:create",
          "profiles:add"
        ]
      }
    },
    "limits": {
      "type": "object",
      "properties": {
        "reads_per_minute_per_key": {
          "const": 60
        },
        "reads_per_minute_per_workspace": {
          "const": 300
        },
        "page_size_max": {
          "const": 100
        },
        "writes_per_minute_per_key": {
          "type": "integer",
          "const": 10
        },
        "writes_per_minute_per_workspace": {
          "type": "integer",
          "const": 50
        },
        "submitted_profiles_per_minute_per_workspace": {
          "type": "integer",
          "const": 1000
        },
        "profiles_per_write_max": {
          "type": "integer",
          "const": 100
        }
      },
      "required": [
        "reads_per_minute_per_key",
        "reads_per_minute_per_workspace",
        "page_size_max",
        "writes_per_minute_per_key",
        "writes_per_minute_per_workspace",
        "submitted_profiles_per_minute_per_workspace",
        "profiles_per_write_max"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "key_id",
    "user_id",
    "workspace_id",
    "scopes",
    "limits"
  ],
  "additionalProperties": false
}

Workspace

Workspace schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "status": {
      "const": "active"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "name",
    "slug",
    "status",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

Report

Report schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "workspace_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "company": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "supplied_domain": {
          "type": "string"
        },
        "root_domain": {
          "type": [
            "string",
            "null"
          ]
        },
        "linkedin_company_url": {
          "type": "string",
          "format": "uri"
        }
      },
      "required": [
        "name",
        "supplied_domain",
        "root_domain",
        "linkedin_company_url"
      ],
      "additionalProperties": false
    },
    "visibility": {
      "enum": [
        "private",
        "public"
      ]
    },
    "archived": {
      "type": "boolean"
    },
    "analysis_state": {
      "enum": [
        "not_requested",
        "queued",
        "running",
        "available",
        "failed"
      ]
    },
    "profile_count": {
      "type": "integer",
      "minimum": 0
    },
    "analyzed_profile_count": {
      "type": "integer",
      "minimum": 0
    },
    "public_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri"
    },
    "workspace_url": {
      "type": "string",
      "format": "uri"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "workspace_id",
    "name",
    "company",
    "visibility",
    "archived",
    "analysis_state",
    "profile_count",
    "analyzed_profile_count",
    "public_url",
    "workspace_url",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

Profile

Profile schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "report_id": {
      "type": "string",
      "format": "uuid"
    },
    "linkedin_url": {
      "type": "string",
      "format": "uri"
    },
    "name": {
      "type": [
        "string",
        "null"
      ]
    },
    "title": {
      "type": [
        "string",
        "null"
      ]
    },
    "headline": {
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "enum": [
        "urls",
        "finder",
        "ops",
        "migration",
        "api_import"
      ]
    },
    "analysis_available": {
      "type": "boolean"
    },
    "added_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "report_id",
    "linkedin_url",
    "name",
    "title",
    "headline",
    "source",
    "analysis_available",
    "added_at"
  ],
  "additionalProperties": false
}

Scan

Scan schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "report_id": {
      "type": "string",
      "format": "uuid"
    },
    "mode": {
      "enum": [
        "full_profile",
        "activity"
      ]
    },
    "status": {
      "enum": [
        "queued",
        "running",
        "completed",
        "partial",
        "failed",
        "inaccessible",
        "cancelled"
      ]
    },
    "counts": {
      "type": "object",
      "properties": {
        "requested": {
          "type": "integer",
          "minimum": 0
        },
        "completed": {
          "type": "integer",
          "minimum": 0
        },
        "warnings": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "requested",
        "completed",
        "warnings",
        "failed"
      ],
      "additionalProperties": false
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "terminal_reason": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "failed",
        "inaccessible",
        "cancelled",
        null
      ]
    }
  },
  "required": [
    "id",
    "report_id",
    "mode",
    "status",
    "counts",
    "created_at",
    "started_at",
    "completed_at",
    "terminal_reason"
  ],
  "additionalProperties": false
}

ContextResponse

ContextResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Context"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

WorkspaceResponse

WorkspaceResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Workspace"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

ReportResponse

ReportResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Report"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

ProfileResponse

ProfileResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Profile"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

ScanResponse

ScanResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Scan"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

ReportCollection

ReportCollection schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Report"
      }
    },
    "page": {
      "type": "object",
      "properties": {
        "next_cursor": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 2048
        }
      },
      "required": [
        "next_cursor"
      ],
      "additionalProperties": false
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "page",
    "request_id"
  ],
  "additionalProperties": false
}

ProfileCollection

ProfileCollection schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Profile"
      }
    },
    "page": {
      "type": "object",
      "properties": {
        "next_cursor": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 2048
        }
      },
      "required": [
        "next_cursor"
      ],
      "additionalProperties": false
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "page",
    "request_id"
  ],
  "additionalProperties": false
}

CreateProfile

CreateProfile schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "linkedin_url"
  ],
  "properties": {
    "linkedin_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "headline": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    }
  }
}

CreateReport

CreateReport schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "company",
    "name"
  ],
  "properties": {
    "company": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "domain",
        "linkedin_company_url"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200
        },
        "domain": {
          "type": "string",
          "maxLength": 2048
        },
        "linkedin_company_url": {
          "type": "string",
          "format": "uri",
          "maxLength": 2048
        }
      }
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "visibility": {
      "enum": [
        "private",
        "public"
      ],
      "default": "private"
    },
    "on_existing": {
      "enum": [
        "create",
        "return_existing"
      ],
      "default": "create"
    },
    "profiles": {
      "type": "array",
      "maxItems": 100,
      "default": [],
      "items": {
        "$ref": "#/components/schemas/CreateProfile"
      }
    }
  }
}

CreationScan

CreationScan schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "mode",
    "status",
    "person_count",
    "company_page_count"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "mode": {
      "enum": [
        "full_profile",
        "activity"
      ]
    },
    "status": {
      "const": "queued"
    },
    "person_count": {
      "type": "integer",
      "minimum": 0
    },
    "company_page_count": {
      "type": "integer",
      "minimum": 0
    }
  }
}

CreationRow

CreationRow schema

{
  "oneOf": [
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "row_number",
        "status",
        "profile_id"
      ],
      "properties": {
        "row_number": {
          "type": "integer",
          "minimum": 1
        },
        "status": {
          "const": "added"
        },
        "profile_id": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "row_number",
        "status",
        "first_row_number"
      ],
      "properties": {
        "row_number": {
          "type": "integer",
          "minimum": 1
        },
        "status": {
          "const": "duplicate_in_input"
        },
        "first_row_number": {
          "type": "integer",
          "minimum": 1
        }
      }
    }
  ]
}

CreatedReportResponse

CreatedReportResponse schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "data"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "outcome",
        "report",
        "scan_requests",
        "profiles"
      ],
      "properties": {
        "outcome": {
          "const": "created"
        },
        "report": {
          "$ref": "#/components/schemas/Report"
        },
        "scan_requests": {
          "type": "array",
          "maxItems": 2,
          "items": {
            "$ref": "#/components/schemas/CreationScan"
          }
        },
        "profiles": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "submitted",
            "added",
            "duplicate_in_input",
            "rows"
          ],
          "properties": {
            "submitted": {
              "type": "integer",
              "minimum": 0
            },
            "added": {
              "type": "integer",
              "minimum": 0
            },
            "duplicate_in_input": {
              "type": "integer",
              "minimum": 0
            },
            "rows": {
              "type": "array",
              "maxItems": 100,
              "items": {
                "$ref": "#/components/schemas/CreationRow"
              }
            }
          }
        }
      }
    }
  }
}

ExistingReportsResponse

ExistingReportsResponse schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "data"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "outcome",
        "existing_reports",
        "next_cursor"
      ],
      "properties": {
        "outcome": {
          "const": "existing"
        },
        "existing_reports": {
          "type": "array",
          "minItems": 1,
          "maxItems": 100,
          "items": {
            "$ref": "#/components/schemas/Report"
          }
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}

ProfileImport

ProfileImport schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "profiles"
  ],
  "properties": {
    "profiles": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CreateProfile"
      },
      "minItems": 1,
      "maxItems": 100
    }
  }
}

ImportPreviewRow

ImportPreviewRow schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "row_number",
    "status"
  ],
  "properties": {
    "row_number": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "status": {
      "enum": [
        "would_add",
        "would_restore",
        "already_present",
        "duplicate_in_input"
      ]
    },
    "duplicate_of_row": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "const": "previously_removed_profile_restored"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

ImportRow

ImportRow schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "row_number",
    "status"
  ],
  "properties": {
    "row_number": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "status": {
      "enum": [
        "added",
        "restored",
        "already_present",
        "duplicate_in_input"
      ]
    },
    "duplicate_of_row": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "const": "previously_removed_profile_restored"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "profile_id": {
      "type": "string",
      "format": "uuid"
    },
    "scan_requests": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "scan_run_id",
          "mode"
        ],
        "properties": {
          "scan_run_id": {
            "type": "string",
            "format": "uuid"
          },
          "mode": {
            "enum": [
              "full_profile",
              "activity"
            ]
          }
        }
      },
      "minItems": 2,
      "maxItems": 2
    }
  }
}

ImportScan

ImportScan schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "scan_run_id",
    "mode",
    "status_at_commit",
    "jobs_created",
    "jobs_coalesced"
  ],
  "properties": {
    "scan_run_id": {
      "type": "string",
      "format": "uuid"
    },
    "mode": {
      "enum": [
        "full_profile",
        "activity"
      ]
    },
    "status_at_commit": {
      "enum": [
        "queued",
        "running",
        "completed",
        "partial",
        "failed",
        "cancelled"
      ]
    },
    "jobs_created": {
      "type": "integer",
      "minimum": 0
    },
    "jobs_coalesced": {
      "type": "integer",
      "minimum": 0
    }
  }
}

ImportValidationResponse

ImportValidationResponse schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "data"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "data": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "validation_only",
        "valid",
        "counts",
        "rows"
      ],
      "properties": {
        "validation_only": {
          "const": true
        },
        "valid": {
          "const": true
        },
        "counts": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "submitted",
            "would_add",
            "would_restore",
            "already_present",
            "duplicate_in_input",
            "would_queue_profiles"
          ],
          "properties": {
            "submitted": {
              "type": "integer",
              "minimum": 0
            },
            "would_add": {
              "type": "integer",
              "minimum": 0
            },
            "would_restore": {
              "type": "integer",
              "minimum": 0
            },
            "already_present": {
              "type": "integer",
              "minimum": 0
            },
            "duplicate_in_input": {
              "type": "integer",
              "minimum": 0
            },
            "would_queue_profiles": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "rows": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ImportPreviewRow"
          },
          "minItems": 1,
          "maxItems": 100
        }
      }
    }
  }
}

ImportReceipt

ImportReceipt schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "report_id",
    "state",
    "counts",
    "rows",
    "scan_requests",
    "created_at",
    "expires_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "report_id": {
      "type": "string",
      "format": "uuid"
    },
    "state": {
      "const": "completed",
      "description": "Import admission is complete. Scan completion is read separately using the returned report and scan IDs."
    },
    "counts": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "submitted",
        "added",
        "restored",
        "already_present",
        "duplicate_in_input",
        "profiles_queued"
      ],
      "properties": {
        "submitted": {
          "type": "integer",
          "minimum": 0
        },
        "added": {
          "type": "integer",
          "minimum": 0
        },
        "restored": {
          "type": "integer",
          "minimum": 0
        },
        "already_present": {
          "type": "integer",
          "minimum": 0
        },
        "duplicate_in_input": {
          "type": "integer",
          "minimum": 0
        },
        "profiles_queued": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ImportRow"
      },
      "minItems": 1,
      "maxItems": 100
    },
    "scan_requests": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ImportScan"
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}

ImportReceiptResponse

ImportReceiptResponse schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "data"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "data": {
      "$ref": "#/components/schemas/ImportReceipt"
    }
  }
}

ImportValidationError

ImportValidationError schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "request_id",
    "error"
  ],
  "properties": {
    "request_id": {
      "type": "string",
      "format": "uuid"
    },
    "error": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message",
        "retryable",
        "details",
        "next_action"
      ],
      "properties": {
        "code": {
          "const": "import_validation_failed"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "const": false
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "field",
              "code"
            ],
            "properties": {
              "row_number": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100
              },
              "field": {
                "enum": [
                  "profiles",
                  "linkedin_url",
                  "name",
                  "title",
                  "headline"
                ]
              },
              "code": {
                "type": "string"
              }
            }
          },
          "maxItems": 100
        },
        "next_action": {
          "type": "string",
          "description": "Safe user-facing guidance for correcting the cause or retrying. Automate using code and retryable, not by parsing this text."
        }
      }
    }
  }
}

AnalysisLimitation

AnalysisLimitation schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": false
}

AnalysisFreshness

AnalysisFreshness schema

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "enum": [
        "current",
        "stale",
        "unknown"
      ]
    },
    "reasons": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "oldest_captured_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "newest_captured_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "state",
    "reasons",
    "oldest_captured_at",
    "newest_captured_at"
  ],
  "additionalProperties": false
}

AnalysisProvenance

AnalysisProvenance schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "scanner",
        "synthetic_demo",
        "legacy",
        "unknown"
      ]
    },
    "scan_run_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ]
    },
    "check_set_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "evaluator_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "check_set_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "source",
    "scan_run_id",
    "check_set_version"
  ],
  "additionalProperties": false
}

AnalysisCounts

AnalysisCounts schema

{
  "type": "object",
  "properties": {
    "good": {
      "type": "integer",
      "minimum": 0
    },
    "optimize": {
      "type": "integer",
      "minimum": 0
    },
    "answered": {
      "type": "integer",
      "minimum": 0
    },
    "unknown": {
      "type": "integer",
      "minimum": 0
    },
    "score_pct": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "good",
    "optimize",
    "answered",
    "unknown",
    "score_pct"
  ],
  "additionalProperties": false
}

AnalysisImageEvidence

AnalysisImageEvidence schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^ev_[a-f0-9]{64}$"
    },
    "variant": {
      "type": "string",
      "enum": [
        "preview",
        "original"
      ]
    },
    "url": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "id",
    "variant",
    "url"
  ],
  "additionalProperties": false
}

AnalysisEvidence

AnalysisEvidence schema

{
  "type": "object",
  "properties": {
    "text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "observed_value": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "kind": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "profile_header",
            "cover",
            "intro",
            "about",
            "experience",
            "featured",
            "visibility",
            "activity",
            "other"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "source_url": {
      "anyOf": [
        {
          "type": "string",
          "format": "uri"
        },
        {
          "type": "null"
        }
      ]
    },
    "images": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AnalysisImageEvidence"
      }
    }
  },
  "required": [
    "text",
    "observed_value",
    "kind",
    "source_url",
    "images"
  ],
  "additionalProperties": false
}

AnalysisCheck

AnalysisCheck schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "revision": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "question_code": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "label": {
      "type": "string"
    },
    "outcome": {
      "type": "string",
      "enum": [
        "good",
        "optimize",
        "unknown"
      ]
    },
    "recommendation": {
      "description": "Stored generic guidance; null for unknown/invalid outcomes. Apply only to optimize findings. Render [company name] or {company} using validated report.company.name or neutral wording. Never rewrite evidence.",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "good_to_know": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "evidence": {
      "$ref": "#/components/schemas/AnalysisEvidence"
    },
    "decision": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "outcome": {
              "type": "string",
              "enum": [
                "good",
                "optimize",
                "inconclusive",
                "invalid"
              ]
            },
            "reason": {
              "type": "string"
            },
            "source": {
              "type": "string"
            },
            "originalAnswer": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ]
            },
            "companyContext": {
              "type": "string",
              "enum": [
                "unknown",
                "matches_request",
                "conflict"
              ]
            }
          },
          "required": [
            "outcome",
            "reason",
            "source",
            "originalAnswer"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "id",
    "revision",
    "question_code",
    "category",
    "label",
    "outcome",
    "recommendation",
    "good_to_know",
    "evidence"
  ],
  "additionalProperties": false
}

AnalysisProfileAnalysis

AnalysisProfileAnalysis schema

{
  "type": "object",
  "properties": {
    "snapshot_id": {
      "type": "string",
      "format": "uuid"
    },
    "revision": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "usable": {
      "type": "boolean"
    },
    "captured_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "available_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "updated_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "provenance": {
      "$ref": "#/components/schemas/AnalysisProvenance"
    },
    "freshness": {
      "$ref": "#/components/schemas/AnalysisFreshness"
    },
    "counts": {
      "$ref": "#/components/schemas/AnalysisCounts"
    },
    "checks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AnalysisCheck"
      }
    },
    "received_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "snapshot_id",
    "revision",
    "usable",
    "captured_at",
    "available_at",
    "updated_at",
    "provenance",
    "freshness",
    "counts",
    "checks"
  ],
  "additionalProperties": false
}

AnalysisProfileResult

AnalysisProfileResult schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "report_id": {
      "type": "string",
      "format": "uuid"
    },
    "revision": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "linkedin_url": {
      "type": "string",
      "format": "uri"
    },
    "analysis": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/AnalysisProfileAnalysis"
        },
        {
          "type": "null"
        }
      ]
    },
    "unavailable_reason": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "not_requested",
            "awaiting_finalization",
            "no_eligible_result",
            "provenance_unknown"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "limitations": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AnalysisLimitation"
      }
    },
    "membership": {
      "type": "string"
    },
    "observation": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "comparison": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "roster_identity": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "identity_source": {
      "type": "string",
      "enum": [
        "captured",
        "imported"
      ]
    }
  },
  "required": [
    "id",
    "report_id",
    "revision",
    "name",
    "title",
    "linkedin_url",
    "analysis",
    "unavailable_reason",
    "limitations"
  ],
  "additionalProperties": false
}

AnalysisActivity

AnalysisActivity schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "report_id": {
      "type": "string",
      "format": "uuid"
    },
    "revision": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "actor_profile_id": {
      "type": "string",
      "format": "uuid"
    },
    "actor_type": {
      "type": "string",
      "enum": [
        "person",
        "company_page"
      ]
    },
    "actor_name": {
      "type": "string"
    },
    "actor_url": {
      "type": "string",
      "format": "uri"
    },
    "event_type": {
      "type": "string",
      "enum": [
        "post",
        "repost",
        "comment",
        "reaction"
      ]
    },
    "source_url": {
      "anyOf": [
        {
          "type": "string",
          "format": "uri"
        },
        {
          "type": "null"
        }
      ]
    },
    "occurred_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "date_precision": {
      "type": "string",
      "enum": [
        "exact",
        "estimated",
        "unknown"
      ]
    },
    "content_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "comment_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "reaction_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "engagement": {
      "type": "object",
      "properties": {
        "scope": {
          "type": "string",
          "enum": [
            "activity",
            "parent"
          ]
        },
        "reactions": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0
            },
            {
              "type": "null"
            }
          ]
        },
        "comments": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0
            },
            {
              "type": "null"
            }
          ]
        },
        "reposts": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0
            },
            {
              "type": "null"
            }
          ]
        },
        "observed_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "scope",
        "reactions",
        "comments",
        "reposts",
        "observed_at"
      ],
      "additionalProperties": false
    },
    "captured_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "available_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "updated_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ]
    },
    "provenance": {
      "$ref": "#/components/schemas/AnalysisProvenance"
    },
    "limitations": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AnalysisLimitation"
      }
    }
  },
  "required": [
    "id",
    "report_id",
    "revision",
    "actor_profile_id",
    "actor_type",
    "actor_name",
    "actor_url",
    "event_type",
    "source_url",
    "occurred_at",
    "date_precision",
    "content_text",
    "comment_text",
    "reaction_type",
    "engagement",
    "captured_at",
    "available_at",
    "updated_at",
    "provenance",
    "limitations"
  ],
  "additionalProperties": false
}

AnalysisWork

AnalysisWork schema

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "enum": [
        "not_requested",
        "queued",
        "processing",
        "completed",
        "completed_with_issues",
        "failed",
        "unknown"
      ]
    },
    "all_requested_work_terminal": {
      "type": "boolean"
    },
    "all_requested_work_succeeded": {
      "type": "boolean"
    },
    "counts": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "requested": {
              "type": "integer",
              "minimum": 0
            },
            "queued": {
              "type": "integer",
              "minimum": 0
            },
            "processing": {
              "type": "integer",
              "minimum": 0
            },
            "succeeded": {
              "type": "integer",
              "minimum": 0
            },
            "failed": {
              "type": "integer",
              "minimum": 0
            },
            "inaccessible": {
              "type": "integer",
              "minimum": 0
            },
            "cancelled": {
              "type": "integer",
              "minimum": 0
            },
            "warnings": {
              "type": "integer",
              "minimum": 0
            }
          },
          "required": [
            "requested",
            "queued",
            "processing",
            "succeeded",
            "failed",
            "inaccessible",
            "cancelled",
            "warnings"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "scan_run_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "maxItems": 2,
      "description": "Latest applicable run per mode, at most two; counts may include units from other runs."
    }
  },
  "required": [
    "state",
    "all_requested_work_terminal",
    "all_requested_work_succeeded",
    "counts",
    "scan_run_ids"
  ],
  "additionalProperties": false
}

AnalysisAggregate

AnalysisAggregate schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "key": {
      "type": "string"
    },
    "good": {
      "type": "integer",
      "minimum": 0
    },
    "optimize": {
      "type": "integer",
      "minimum": 0
    },
    "answered": {
      "type": "integer",
      "minimum": 0
    },
    "score_pct": {
      "anyOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "revision": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "id",
    "key",
    "good",
    "optimize",
    "answered",
    "score_pct",
    "revision"
  ],
  "additionalProperties": false
}

AnalysisOptimizationSummary

AnalysisOptimizationSummary schema

{
  "type": "object",
  "properties": {
    "method": {
      "type": "string",
      "enum": [
        "conclusive_selected_observation_checks",
        "existing_profile_check_aggregation"
      ]
    },
    "cohort_profile_count": {
      "type": "integer",
      "minimum": 0
    },
    "counts": {
      "$ref": "#/components/schemas/AnalysisCounts"
    },
    "categories": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AnalysisAggregate"
      }
    },
    "checks": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AnalysisAggregate"
      }
    }
  },
  "required": [
    "method",
    "cohort_profile_count",
    "counts",
    "categories",
    "checks"
  ],
  "additionalProperties": false
}

AnalysisSummary

AnalysisSummary schema

{
  "type": "object",
  "properties": {
    "report": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string"
        },
        "archived": {
          "type": "boolean"
        },
        "company": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "domain": {
              "type": "string"
            },
            "linkedin_url": {
              "type": "string",
              "format": "uri"
            },
            "observed_context": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "tagline": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "industry": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "captured_at": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "date-time"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "provenance": {
                      "$ref": "#/components/schemas/AnalysisProvenance"
                    }
                  },
                  "required": [
                    "tagline",
                    "industry",
                    "captured_at",
                    "provenance"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "name",
            "domain",
            "linkedin_url",
            "observed_context"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "id",
        "name",
        "archived",
        "company"
      ],
      "additionalProperties": false
    },
    "links": {
      "type": "object",
      "properties": {
        "workspace_url": {
          "type": "string",
          "format": "uri"
        },
        "public_url": {
          "anyOf": [
            {
              "type": "string",
              "format": "uri"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "workspace_url",
        "public_url"
      ],
      "additionalProperties": false
    },
    "availability": {
      "type": "string",
      "enum": [
        "none",
        "partial",
        "available"
      ]
    },
    "has_usable_results": {
      "type": "boolean"
    },
    "coverage": {
      "type": "object",
      "properties": {
        "person_profiles": {
          "type": "integer",
          "minimum": 0
        },
        "optimization": {
          "type": "object",
          "properties": {
            "analyzed_profiles": {
              "type": "integer",
              "minimum": 0
            },
            "answered_checks": {
              "type": "integer",
              "minimum": 0
            },
            "unknown_checks": {
              "type": "integer",
              "minimum": 0
            },
            "profiles_without_usable_analysis": {
              "type": "integer",
              "minimum": 0
            }
          },
          "required": [
            "analyzed_profiles",
            "answered_checks",
            "unknown_checks",
            "profiles_without_usable_analysis"
          ],
          "additionalProperties": false
        },
        "activity": {
          "type": "object",
          "properties": {
            "observed_person_profiles": {
              "type": "integer",
              "minimum": 0
            },
            "company_page_observed": {
              "type": "boolean"
            },
            "incomplete_person_profiles": {
              "type": "integer",
              "minimum": 0
            }
          },
          "required": [
            "observed_person_profiles",
            "company_page_observed",
            "incomplete_person_profiles"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "person_profiles",
        "optimization",
        "activity"
      ],
      "additionalProperties": false
    },
    "work": {
      "$ref": "#/components/schemas/AnalysisWork"
    },
    "freshness": {
      "$ref": "#/components/schemas/AnalysisFreshness"
    },
    "evaluated_at": {
      "type": "string",
      "format": "date-time"
    },
    "results_revision": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "work_revision": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "collections": {
      "type": "object",
      "properties": {
        "profiles_revision": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "activity_revision": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        }
      },
      "required": [
        "profiles_revision",
        "activity_revision"
      ],
      "additionalProperties": false
    },
    "optimization_summary": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/AnalysisOptimizationSummary"
        },
        {
          "type": "null"
        }
      ]
    },
    "limitations": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AnalysisLimitation"
      }
    },
    "period": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "monthly_profile_summary": {
      "anyOf": [
        {
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "report",
    "links",
    "availability",
    "has_usable_results",
    "coverage",
    "work",
    "freshness",
    "evaluated_at",
    "results_revision",
    "work_revision",
    "collections",
    "optimization_summary",
    "limitations"
  ],
  "additionalProperties": false
}

AnalysisSummaryResponse

AnalysisSummaryResponse schema

{
  "type": "object",
  "properties": {
    "data": {
      "$ref": "#/components/schemas/AnalysisSummary"
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "request_id"
  ],
  "additionalProperties": false
}

AnalysisProfilePage

AnalysisProfilePage schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AnalysisProfileResult"
      }
    },
    "revision": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "revision",
    "next_cursor",
    "request_id"
  ],
  "additionalProperties": false
}

AnalysisActivityPage

AnalysisActivityPage schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/AnalysisActivity"
      }
    },
    "revision": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "next_cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "data",
    "revision",
    "next_cursor",
    "request_id"
  ],
  "additionalProperties": false
}

AnalysisError

AnalysisError schema

{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "next_action": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message",
        "retryable",
        "next_action"
      ],
      "additionalProperties": false
    },
    "request_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "error",
    "request_id"
  ],
  "additionalProperties": false
}

Endpoint reference

Pagination and responses

GET/context

Read the calling key's workspace and permissions

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

GET/workspace

Read the bound workspace

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

GET/reports

List workspace reports

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

POST/reports

Create a report and queue supplied profiles

HTTP 200

HTTP 201

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 409

HTTP 413

HTTP 415

HTTP 422

HTTP 429

HTTP 500

HTTP 503

GET/reports/{report_id}

Read one report

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

GET/reports/{report_id}/profiles

List active personal profile attachments

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

GET/reports/{report_id}/scans/{scan_run_id}

Read scan status and counts

HTTP 200

HTTP 400

HTTP 401

HTTP 403

HTTP 404

HTTP 429

HTTP 500

HTTP 503

POST/reports/{report_id}/profile-imports

Validate or add people to an existing report

HTTP 200

GET`/context`

GET`/workspace`

GET`/reports`

POST`/reports`

GET`/reports/{report_id}`

GET`/reports/{report_id}/profiles`

GET`/reports/{report_id}/scans/{scan_run_id}`

POST`/reports/{report_id}/profile-imports`

GET`/reports/{report_id}/profile-imports/{import_id}`

GET`/reports/{report_id}/analysis`

GET`/reports/{report_id}/analysis/profiles`

GET`/reports/{report_id}/analysis/activity`

GET`/reports/{report_id}/analysis/evidence/{evidence_id}`