API Reference

The pycli REST API lets you create, retrieve, list, and cancel orders programmatically over HTTP. Use these endpoints to integrate order management into your own applications or automate workflows that would otherwise require manual interaction through the CLI.

Parameters vary by endpoint. See the per-endpoint tables below.

GET /orders/{order_id} — Fetch a single order

POST /orders — Create an order

Send a JSON body with the following fields:

GET /orders — List orders

DELETE /orders/{order_id} — Cancel an order

All successful responses use HTTP 200 OK and return JSON.

GET /orders/{order_id}

Returns a single order object:

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

POST /orders

Returns the newly created order object with an assigned id and a status of "pending":

{
  "id": 1,
  "amount": 250,
  "currency": "EUR",
  "status": "pending"
}

GET /orders

Returns a JSON object containing the applied filter parameters and an array of matching orders:

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

DELETE /orders/{order_id}

Returns a confirmation object showing the order ID and its updated status:

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

The API returns standard HTTP error codes when a request cannot be completed.

The examples below use curl. Replace https://api.example.com with your actual base URL.

Fetch a single order by ID

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

Expected response:

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

Create a new order

curl -X POST https://api.example.com/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": 250, "currency": "EUR", "note": "Rush delivery"}'

Expected response:

{
  "id": 1,
  "amount": 250,
  "currency": "EUR",
  "status": "pending"
}

Create an order without an optional note

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

Expected response:

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

List orders filtered by status

curl -X GET "https://api.example.com/orders?status=pending&limit=5"

Expected response:

{
  "status": "pending",
  "limit": 5,
  "orders": []
}

Cancel an order

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

Expected response:

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

Example of a validation error (missing required field)

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

Expected response (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

• amount is an integer. The API represents monetary amounts as whole numbers. Decide on a convention with your team — for example, storing cents rather than dollars — and apply it consistently across all requests. Sending a floating-point value (e.g., 9.99) will result in a 422 validation error.
• Query parameter defaults. When you call GET /orders without specifying status or limit, the API automatically applies status=paid and limit=20. Always pass these parameters explicitly in production code to avoid unintended filtering behavior.
• note is truly optional. You may omit the note field entirely from the POST /orders request body, or include it with a null value — both are valid.
• Path parameters must be integers. Both GET /orders/{order_id} and DELETE /orders/{order_id} require order_id to be a valid integer. Passing a non-numeric value (e.g., /orders/abc) will result in a 422 validation error.
• Authentication. The source code does not define any authentication mechanism. Consult your deployment configuration or contact your infrastructure team to determine what authentication headers or tokens (if any) are required in your environment.
• DELETE is not reversible. Canceling an order via DELETE /orders/{order_id} sets its status to "canceled". There is no undo endpoint — verify the correct order_id before sending this request.