API Reference

The Ichiba API gives you programmatic access to the marketplace. All endpoints return JSON and require a Bearer token. The base URL is https://api.ichiba.tech.

Search with natural language

Find compute or block storage across every provider on the marketplace using plain English — filter by vCPUs, memory, architecture, price, region, and more.

Purchase resources programmatically

Buy any active listing and the seller's gateway provisions the resource automatically. Cancel purchases when you're done and the resource is deprovisioned.

Manage your listings

Create, update, publish, and delete compute and block storage listings for your organization — with full spec metadata for buyers to filter on.

Build procurement pipelines

Automate infrastructure acquisition: query the market, compare specs and prices, purchase on match, and track your active resources — all without touching a UI.

Authentication

All endpoints require a Bearer token in the Authorization header. Generate tokens from your organization's API Tokens section in the web app.

curl https://api.ichiba.tech/api/listings/active \

  -H "Authorization: Bearer ichiba_..."

Organization

GET /api/organization Show the authenticated organization

Returns the organization associated with the authenticated token.

Example response

{
  "id": 1,
  "name": "Acme Corp"
}

Listings

Manage listings belonging to the authenticated organization.

GET /api/listings List organization listings

Returns all listings for the authenticated organization. Optionally filter by status.

Query parameters

Parameter	Values	Description
`status`	`draft`, `active`, `sold`, `archived`	Filter by listing status

curl "https://api.ichiba.tech/api/listings?status=active" \

  -H "Authorization: Bearer ichiba_..."

GET /api/listings/:id Show a single listing

Returns full detail for a listing including instance_type_spec and network_spec when configured.

Example response

Compute listing

{
  "id": 1,
  "name": "c5.xlarge",
  "description": "Compute-optimized instance",
  "asset_type": "compute",
  "price": "0.17",
  "status": "active",
  "updated_at": "2026-01-15T10:30:00",
  "organization": { "id": 1, "name": "AWS" },
  "instance_type_spec": {
    "family": "compute",
    "vcpus": 4,
    "memory_gb": "8",
    "cpu_architecture": "x86_64",
    "storage_gb": null,
    "storage_type": null,
    "gpu_model": null,
    "gpu_count": null,
    "network_gbps": "10",
    "region": "us-east-1"
  },
  "network_spec": {
    "ipv4_included": true,
    "byoip_supported": true,
    "ipv6_supported": true,
    "private_networking": true,
    "bandwidth_gb": null,
    "ingress_price_per_gb": "0.0000",
    "egress_price_per_gb": "0.0900",
    "max_throughput_gbps": "10"
  }
}

Block storage listing

{
  "id": 2,
  "name": "Standard Block Storage",
  "description": "Multi-region replicated block storage",
  "asset_type": "block_storage",
  "price": "0.10",
  "status": "active",
  "updated_at": "2026-01-15T10:30:00",
  "organization": { "id": 1, "name": "Acme Cloud" },
  "block_storage_spec": {
    "capacity_gb": "500",
    "storage_class": "standard",
    "redundancy": "multi_region",
    "max_iops": 10000,
    "max_throughput_mbps": "500",
    "region": "nyc3"
  }
}

instance_type_spec and network_spec are only present on compute listings. block_storage_spec is only present on block storage listings. All three are omitted when not configured.

POST /api/listings Create a listing

Optionally include an instance_type_spec and/or network_spec object for compute listings, or a block_storage_spec object for block storage listings.

Compute listing

{
  "listing": {
    "name": "My Instance",
    "description": "Optional description",
    "asset_type": "compute",
    "price": "10.00",
    "status": "draft"
  },
  "instance_type_spec": {
    "family": "compute",
    "vcpus": 4,
    "memory_gb": "8",
    "cpu_architecture": "x86_64",
    "network_gbps": "10"
  },
  "network_spec": {
    "ipv4_included": true,
    "ipv6_supported": true,
    "byoip_supported": false,
    "private_networking": true,
    "egress_price_per_gb": "0.09"
  }
}

Block storage listing

{
  "listing": {
    "name": "My Storage Volume",
    "asset_type": "block_storage",
    "price": "0.10",
    "status": "draft"
  },
  "block_storage_spec": {
    "capacity_gb": "500",
    "storage_class": "standard",
    "redundancy": "replicated",
    "max_iops": 5000,
    "max_throughput_mbps": "250",
    "region": "us-east-1"
  }
}

PUT /api/listings/:id Update a listing

Also accepts PATCH. Uses the same request body shape as create.

DELETE /api/listings/:id Delete a listing

Permanently deletes a listing belonging to the authenticated organization.

Active listings

Browse all active listings across every organization on the marketplace.

GET /api/listings/active All active listings across organizations

Returns all listings with status: "active" regardless of organization. Each listing includes an organization object with id and name.

curl https://api.ichiba.tech/api/listings/active \

  -H "Authorization: Bearer ichiba_..."

POST /api/listings/search Search active listings with a natural language query

Runs a 3-step AI pipeline — parse query → database filter → summarise — and returns ranked results with per-listing highlights. Supports natural language constraints for both compute (vCPUs, memory, CPU architecture, instance family, GPU, network specs) and block storage (capacity, IOPS, throughput, storage class, redundancy), as well as price, result count, provider diversity, provider name, region, and sort order. Block storage listings in the response include a block_storage_spec field instead of instance_type_spec.

Request body

{ "query": "8 ARM64 vCPUs, 32 GB RAM, under $2/hour" }

Example response

{
  "summary": "All 3 results are ARM64 compute instances priced under $2/hour...",
  "listings": [
    {
      "id": 1,
      "name": "a2.large",
      "description": "ARM-based compute instance",
      "asset_type": "compute",
      "price": "1.20",
      "highlight": "Best value option with NVMe storage and 25 Gbps networking.",
      "organization": { "id": 1, "name": "Acme Cloud" },
      "instance_type_spec": {
        "family": "compute",
        "vcpus": 8,
        "memory_gb": "32",
        "cpu_architecture": "arm64",
        "storage_gb": 100,
        "storage_type": "nvme",
        "gpu_model": null,
        "gpu_count": null,
        "network_gbps": "25"
      },
      "network_spec": {
        "ipv4_included": true,
        "byoip_supported": false,
        "ipv6_supported": true,
        "private_networking": true,
        "bandwidth_gb": null,
        "max_throughput_gbps": "25"
      }
    }
  ],
  "count": 1,
  "has_more": false
}

instance_type_spec and network_spec are omitted for listings where they have not been configured.

Purchases

Buy active listings and manage your organization's purchases.

POST /api/listings/:listing_id/purchase Purchase a listing

Provisions a resource from the seller's gateway and creates a purchase record. The authenticated organization must be approved as a buyer and cannot purchase its own listings.

Example response (202)

The purchase is created with status: "pending" and provisioned asynchronously. Poll GET /api/purchases/:id to check when it becomes active.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "listing_id": 1,
  "gateway_tenant_id": null,
  "status": "pending",
  "access_details": null
}

Error responses

Status	Body	Cause
403	`{"error": "This organization is not approved to purchase."}`	Org not approved as buyer
403	`{"error": "A valid payment method is required to purchase."}`	No payment method on file
403	`{"error": "Cannot purchase your own listing."}`	Buyer and seller are the same org
404	`{"error": "not found"}`	Listing does not exist
422	`{"error": "Listing is not active."}`	Listing not in active status
422	`{"error": "Seller has not configured a payment gateway."}`	Seller gateway missing
422	`{"error": "This seller requires credentials. Please configure your credentials for this seller before purchasing."}`	Buyer has not set up seller credentials

GET /api/purchases List organization purchases

Returns all purchases made by the authenticated organization, ordered by most recent first. Optionally filter by status.

Query parameters

Parameter	Values	Description
`status`	`pending`, `active`, `cancelled`, `failed`	Filter by purchase status

Example response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "listing_id": 1,
    "status": "active",
    "gateway_tenant_id": "tenant_abc123",
    "inserted_at": "2026-01-15T10:30:00"
  }
]

GET /api/purchases/:id Show a single purchase

Returns full detail for a purchase including access_details once provisioning completes. Poll this endpoint after creating a purchase to detect when it transitions from pending to active or failed.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "listing_id": 1,
  "status": "active",
  "gateway_tenant_id": "tenant_abc123",
  "access_details": { ... },
  "error_message": null,
  "inserted_at": "2026-01-15T10:30:00"
}

access_details is populated by the seller's gateway once provisioning completes. error_message is set if the purchase transitions to failed.

DELETE /api/purchases/:id Cancel a purchase

Cancels an active purchase. If the seller has a gateway configured, the gateway is notified to deprovision the resource.

Example response

{ "id": "550e8400-e29b-41d4-a716-446655440000", "status": "cancelled" }

Error responses

Status	Body	Cause
404	`{"error": "not found"}`	Purchase not found or belongs to another org
422	`{"error": "Purchase is not active."}`	Purchase already cancelled

Sellers

Retrieve information about approved sellers on the marketplace.

GET /api/sellers List all approved sellers

Returns all seller-approved organizations with public metadata: active listing counts by asset type, credential fields buyers must configure before purchasing, and any required permissions at the seller's site.

Example response

[
  {
    "id": 1,
    "name": "Acme Cloud",
    "description": "Fast, reliable cloud compute and storage.",
    "website": "https://acme.example.com",
    "listing_counts": {
      "compute": 12,
      "block_storage": 4
    },
    "credential_fields": [
      { "name": "api_key", "label": "API Key" },
      { "name": "project_id", "label": "Project ID" }
    ],
    "required_permissions": "Storage Admin, Compute Viewer"
  }
]

Field	Description
`listing_counts`	Map of asset type to count of active listings. Only types with at least one active listing are included.
`credential_fields`	Fields the buyer must supply before purchasing from this seller (e.g. API key, project ID). Empty if no credentials are required.
`required_permissions`	Free-text description of permissions a buyer must configure at the seller's site before purchasing. `null` if none.

Listing statuses

Status	Description	Visible to other orgs?
draft	Work in progress, not yet published	No
active	Published and available to buyers	Yes
sold	Transaction complete	No
archived	Removed from market, kept for records	No

Purchase statuses

Status	Description
pending	Purchase created, provisioning in progress
active	Provisioning complete — `access_details` populated
failed	Provisioning failed — check `error_message`
cancelled	Cancelled by buyer; gateway notified to deprovision