> For the complete documentation index, see [llms.txt](https://docs.flashback.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flashback.tech/flashgate-platform/isp-market/api-interactions.md).

# API Interactions

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Client
    participant API as Flashgate API
    participant Market as Market Service
    participant Orch as Orchestrator
    participant Adapter as Provider Adapter
    participant Provider
    participant Metrics as Metrics Service

    Client->>API: GET /market/offerings
    API->>Market: Query offerings
    Market-->>API: Offerings list
    API-->>Client: 200 Offerings

    Client->>API: POST /allocations/reserve
    API->>Market: Reserve Data Unit
    Market->>Orch: Reservation event
    Orch->>Adapter: Provision / allocate request
    Adapter->>Provider: Allocate Data Unit
    Provider-->>Adapter: Allocation confirmed
    Adapter-->>Orch: Allocation result
    Orch-->>API: Allocation status
    API-->>Client: 202 Reserved / Allocating

    Provider->>Metrics: Push telemetry
    Orch->>Metrics: Pull metrics and health

    Client->>API: GET /allocations/{id}
    API->>Orch: Read allocation status
    Orch-->>API: Status and routing details
    API-->>Client: 200 Allocation status
```

***

## **Oracles**

Oracles bridge on-chain and off-chain data by providing real-time verification signals to orchestrators (for example integrity checks, usage telemetry, pricing updates, and SLA evidence). They act as trusted validation intermediaries for service quality.

***

## **Suite API Model (Data Unit-Centric)**

The ISP Market no longer assumes one universal "standard API" for every resource type. Instead, API interactions are centered around the **allocated Data Unit** and its compatible access model.

* **Allocation-first flow**:
  * A Consumer selects and pays for a Data Unit in the marketplace.
  * After allocation, the platform generates credentials tied to that Data Unit.
* **Protocol compatibility by unit type**:
  * Storage Data Units can generate **S3-compatible keys** (and compatible endpoint details).
  * Other Data Unit categories can expose their own compatible access patterns through the Suite API layer.
* **Security scope**:
  * Credentials are scoped to the purchased allocation and lifecycle.
  * Access can be rotated/revoked based on policy, SLA state, or expiration.

This model gives Providers flexibility to expose resources with clear compatibility constraints, while giving Consumers an operational experience aligned with the selected unit.

***

## **Interactions Between Layers**

1. **Providers ↔ Suite APIs ↔ Orchestrator**:
   * Providers register Data Units and supported compatibility profiles.
   * The Orchestrator tracks lifecycle states and enforces policy conditions.
2. **Consumers ↔ Suite APIs ↔ Orchestrator**:
   * Consumers allocate and pay for a Data Unit.
   * The platform issues Data Unit-compatible credentials after successful allocation.
3. **Oracles ↔ Orchestrator ↔ Suite APIs**:
   * Oracles submit validated QoS/SLA evidence.
   * Orchestrator decisions can impact API access state (active, restricted, expired).

***

## **Practical Note for Storage Units**

For storage-focused Data Units, the default operational pattern is:

1. Select a storage Data Unit in ISP Market.
2. Purchase/allocate the Data Unit.
3. Receive generated S3-compatible credentials and endpoint details.
4. Interact directly with the allocated storage unit using these credentials.

As new Data Unit types are introduced, the same allocation-first principle applies, with compatibility determined by each unit profile.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flashback.tech/flashgate-platform/isp-market/api-interactions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.