Key Concepts

This page explains the core concepts behind pycli's HTTP API — the resources it exposes, how requests and responses are structured, and the design patterns you'll encounter when integrating with it. Understanding these fundamentals will help you use the API predictably and handle edge cases with confidence.

Resources

The pycli API is organized around a single primary resource: orders. An order represents a transactional record with a monetary amount, a currency, and a lifecycle status. Every order is identified by a unique integer id assigned by the server at creation time.

Orders have the following fields:

Request and response format

All request and response bodies use JSON. When sending a request body (for example, when creating an order), you must include the header Content-Type: application/json.

Response bodies are always JSON objects or JSON arrays of objects. The API does not use envelope wrappers — a successful GET /orders/{order_id} returns the order object directly, not nested inside a data key.

Creating an order

To create an order, you POST to /orders with a JSON body that conforms to the CreateOrderBody schema:

The server validates the body against this schema. Providing the wrong type for a required field, or omitting a required field entirely, will result in a validation error.

A newly created order always has status: "pending".

Order lifecycle

An order moves through statuses over its lifetime. The statuses you will encounter in practice are:

• pending — the order has been created but not yet processed.
• paid — the order has been fulfilled.
• canceled — the order was canceled via a DELETE request.

When you cancel an order by calling DELETE /orders/{order_id}, the response confirms the cancellation by returning the order id and status: "canceled".

Filtering and pagination

The GET /orders endpoint accepts query parameters that let you narrow results without fetching every order:

Because status defaults to "paid", a plain GET /orders with no parameters returns only paid orders. Pass status=pending (or any other status value) explicitly if you need orders in a different state.

Path parameters

Endpoints that operate on a specific order use an order_id path parameter, which must be an integer. Passing a non-integer value (for example, a string like "abc") will produce a validation error from the server before your handler logic is reached.

API surface summary

Create an order

Submit a POST request with the required amount and currency fields. The optional note field is omitted here.

curl -X POST https://api.example.com/orders \
  -H 'Content-Type: application/json' \
  -d '{"amount": 1500, "currency": "USD"}'

Expected response:

{
  "id": 1,
  "amount": 1500,
  "currency": "USD",
  "status": "pending"
}

Fetch a single order

Retrieve an order by its integer id.

curl https://api.example.com/orders/42

Expected response:

{
  "id": 42,
  "amount": 100,
  "currency": "USD",
  "status": "paid"
}

List paid orders with a limit

Use query parameters to filter by status and cap the number of results returned.

curl 'https://api.example.com/orders?status=paid&limit=10'

Expected response:

{
  "status": "paid",
  "limit": 10,
  "orders": []
}

Cancel an order

Send a DELETE request to cancel an order. The response confirms the new status.

curl -X DELETE https://api.example.com/orders/42

Expected response:

{
  "id": 42,
  "status": "canceled"
}

• Install pycli — Set up pycli before making your first API call.
• Deploy a stack — Understand how the CLI deploy command relates to the broader pycli workflow.
• Create an order — Step-by-step guide to placing your first order through the API.
• List and filter orders — Learn how to use status and limit query parameters effectively.
• Cancel an order — Details on the order cancellation flow and what to expect in the response.