Partner API

The RICA Atlas Partner API allows approved software and workflow partners to connect with Atlas as the operating record for projects, evidence, metrics, origination workflows, project loans, note monitoring, and portfolio outputs.

This page documents the current working surface. It is an integration guide, not a fully versioned public API contract or SDK specification. Partners coordinate with the platform team before relying on behavior that is not explicitly documented for their environment.

API Posture

Atlas exposes a REST-style API rooted at /v1, with the same routes also available under /api/v1. Most business responses return JSON envelopes with a data field. Validation failures return structured details with field paths and messages.

Convention	Current Surface
Primary API root	/v1
Mirrored API root	/api/v1
Health endpoint	GET /v1/health
Response style	JSON envelopes, typically with data
Validation style	Structured details with field paths and messages

Authentication Modes

Atlas currently supports two authentication patterns.

Production-Oriented Bearer Authentication

When Cognito mode is active, requests use bearer authentication:

Authorization: Bearer <token>

Authenticated routes resolve the acting user from the bearer token.

Internal Or Header-Based Authentication

In local or header mode, requests identify the acting user through request headers:

x-user-id: <user uuid>
x-org-id: <organization uuid>
x-role: <role code>
x-org-admin: true|false
x-platform-admin: true|false

This mode supports development, testing, and controlled integration work. It is not the long-term production authentication contract.

Integration Domains

Domain	Business Purpose
Identity and session bootstrap	Establish user, role, organization, and desk context.
Organizations and reference data	Synchronize institutional records, members, countries, districts, and currencies.
Projects, discovery, and search	Find visible projects and retrieve asset-level records.
Documents and media	Upload, register, retrieve, and govern evidence and investor materials.
Metrics and verification	Maintain metric definitions, assignments, submissions, and review workflows.
Origination, loans, and portfolio	Support project screening, loan proposals, activation, servicing, and portfolio visibility.
Notes and monitoring	Expose note records, pool composition, documents, cash flows, distributions, and investor workflows.

Representative Endpoints

Identity And Session Bootstrap

• POST /v1/auth/bootstrap
• POST /v1/auth/login
• GET /v1/me
• GET /v1/users/me
• PATCH /v1/users/me
• GET /v1/users/me/overview

Organizations And Reference Data

• POST /v1/organizations
• GET /v1/organizations
• GET /v1/organizations/:organizationId
• PATCH /v1/organizations/:organizationId
• GET /v1/organizations/:organizationId/members
• POST /v1/organizations/:organizationId/members
• PATCH /v1/organizations/:organizationId/members/:memberId
• GET /v1/reference/countries
• GET /v1/reference/districts
• GET /v1/reference/currencies

Projects, Discovery, And Search

• GET /v1/projects
• GET /v1/projects/:projectId
• GET /v1/discover/...
• GET /v1/search/...

Documents And Media

• GET /v1/projects/:projectId/documents
• POST /v1/projects/:projectId/documents
• DELETE /v1/projects/:projectId/documents/:documentId
• GET /v1/projects/:projectId/media
• POST /v1/projects/:projectId/media
• PATCH /v1/projects/:projectId/media/:mediaId
• DELETE /v1/projects/:projectId/media/:mediaId
• POST /v1/storage/documents/presign-upload
• PUT /v1/storage/documents/direct-upload/:storageKey
• GET /v1/storage/documents/object/:storageKey

Metrics And Verification

• GET /v1/metrics/definitions
• GET /v1/metrics/framework-defaults
• POST /v1/metrics/definitions
• PATCH /v1/metrics/definitions/:metricId
• GET /v1/projects/:projectId/metrics/assignments
• POST /v1/projects/:projectId/metrics/assignments
• PATCH /v1/projects/:projectId/metrics/assignments/:assignmentId
• POST /v1/projects/:projectId/metrics/assignments/:assignmentId/retire
• GET /v1/projects/:projectId/metrics/submissions
• POST /v1/projects/:projectId/metrics/submissions
• GET /v1/projects/:projectId/metrics/latest-values
• GET /v1/projects/:projectId/metrics/kpis
• GET /v1/projects/:projectId/metrics/dashboard
• POST /v1/metrics/submissions/:submissionId/auditor-review
• POST /v1/metrics/submissions/:submissionId/platform-approval

Origination, Loans, And Portfolio

• GET /v1/rica-investor/opportunities
• GET /v1/rica-investor/opportunities/:projectId/profile
• GET /v1/rica-investor/underwriting-workbench
• GET /v1/investor-pipeline
• POST /v1/investor-pipeline
• PATCH /v1/investor-pipeline/:pipelineId
• GET /v1/projects/:projectId/loan-proposals
• POST /v1/projects/:projectId/loan-proposals
• GET /v1/origination/loan-proposals
• POST /v1/origination/loan-proposals/:proposalId/approve
• POST /v1/origination/loan-proposals/:proposalId/decline
• POST /v1/origination/loan-proposals/:proposalId/activate
• GET /v1/projects/:projectId/loans
• POST /v1/projects/:projectId/loans
• PATCH /v1/projects/:projectId/loans/:loanId
• GET /v1/projects/:projectId/loans/:loanId/schedule
• GET /v1/project-loans/:loanId/servicing
• POST /v1/admin/project-loans/:loanId/servicing/rebuild
• POST /v1/admin/project-loans/:loanId/servicing-events
• GET /v1/rica-investor/loan-portfolio
• GET /v1/portfolio-positions

Notes And Monitoring

• GET /v1/notes
• GET /v1/notes/compare
• GET /v1/notes/:noteId
• GET /v1/notes/:noteId/projects
• GET /v1/notes/:noteId/documents
• GET /v1/notes/:noteId/cashflows
• GET /v1/notes/:noteId/distributions
• GET /v1/notes/:noteId/loan-purchases
• POST /v1/notes/:noteId/request-materials
• POST /v1/notes/:noteId/questions
• GET /v1/notes/:noteId/my-interest-requests

Document Upload Sequence

1. Request upload target from /v1/storage/documents/presign-upload
2. Upload the binary to the returned target
3. Register the uploaded file with POST /v1/projects/:projectId/documents
4. Allow Atlas worker flows and review policies to govern downstream access

Representative Integration Patterns

Sponsor System To Atlas

Sponsor systems can synchronize organization and user identities, create or update project records, upload evidence, push metrics submissions, and respond to loan proposal or data-request states.

Partner Data Room Or Workflow Tool To Atlas

Workflow tools can pull project, document, and note detail from Atlas, reference Atlas IDs as canonical records, and write back review outcomes, document metadata, or workflow events where supported.

Monitoring Stack To Atlas

Monitoring systems can fetch KPI, metrics, servicing, and portfolio endpoints, maintain downstream dashboards, and preserve Atlas as the authoritative source for operating state.

Integration Discipline

Partners design for version discipline, permission checks, pagination, retries, idempotency where applicable, request tracing, and environment-specific test data. API formalization covers route versioning, pagination and filtering conventions, rate limits, webhook events, schema examples, changelog practices, and a stable error model.