# Self Bank Agent API

Sandbox-first agent integration contract for selected Self Bank capabilities.

- Base URL: `https://cube.self.team/api/agent/v1`
- OpenAPI contract: https://cube.self.team/api/openapi-agent-v1.yaml
- Status: sandbox-first public contract artifact

## Intended usage model

- Agents use the API to explore Self Bank capabilities and validate integrations under sandbox conditions.
- The API is not a production banking API and does not expose real customer data, real accounts, or real fund movement.
- Production-affecting flows are gated by explicit Self Bank enablement, outside this public surface.

## API contract summary

- Specification: OpenAPI 3.1, published at `/api/openapi-agent-v1.yaml`.
- Transport: HTTPS, JSON request and response bodies.
- All successful responses include an `environment` field set to `sandbox`.
- All error responses follow a uniform `ErrorResponse` schema.

## Authentication model

- Scheme: HTTP Bearer (JWT).
- Tokens are scope-limited; each endpoint requires a specific scope.
- Tokens are not self-service; issuance is governed by Self Bank.
- Missing or invalid tokens return `401`; insufficient scopes return `403`.

## Versioning and rollout model

- URL versioning: `/api/agent/v1`.
- Backwards-incompatible changes will be introduced via a new path version.
- Endpoints may be marked as `Sandbox available` or `Planned capability`.
- Planned capabilities may exist as contract artifacts before general sandbox availability.

## Usage constraints

- Sandbox-only: no production side effects, no real fund movement, no real customers created.
- Validation: requests must conform to the OpenAPI 3.1 contract; invalid bodies return `400`.
- Stability and rate limits are not guaranteed for the public sandbox surface.
- Use of the API implies acceptance of the sandbox-first boundary.

## Response patterns

- Success responses include an `environment` field and operation-specific identifiers (for example, `simulationId`, `summaryId`).
- Error envelope:
  - `error.code` — machine-readable code
  - `error.message` — human-readable summary
  - `error.details` — optional structured details
  - `error.requestId` — correlation identifier

## Available endpoints

### Catalog
- `GET /catalog/products` — Retrieve Self Bank product and service catalog
  - Scope: `catalog.read`
  - Filters: `category`, `clientType`, `country`
  - Availability: Sandbox available

### Simulations
- `POST /simulations/onboarding` — Simulate corporate onboarding flow
  - Scope: `simulation.onboarding`
  - Availability: Sandbox available
- `POST /simulations/payments` — Simulate payment validation and routing flow
  - Scope: `simulation.payments`
  - Availability: Sandbox available
- `POST /simulations/account-opening` — Simulate account-opening lifecycle
  - Scope: `simulation.account_opening`
  - Availability: Sandbox available

### Analytics
- `POST /analytics/summary` — Generate operational analytics summary
  - Scope: `analytics.summary.read`
  - Availability: Planned capability

## Planned capability notes

- `POST /analytics/summary` is exposed in the contract and may evolve before general sandbox availability.
- New endpoints will appear first as sandbox-only and will be reflected in the OpenAPI contract.

## Related resources

- Agent skills: https://cube.self.team/agents/skills
- Integration guide: https://cube.self.team/docs/agent-integration
- OpenAPI contract: https://cube.self.team/api/openapi-agent-v1.yaml