REST Endpoints

This page documents every HTTP endpoint exposed by the pycli REST API, including request schemas, query parameters, path parameters, and response shapes. Use this reference when integrating order management into your application or automating deployments from your own tooling. All interactions with pycli happen over HTTP — there is no SDK required beyond an HTTP client. Keeping this page open alongside your code will save you time when debugging request validation errors or unexpected response structures.

Before making requests to the pycli API, make sure you have:

• pycli installed on your machine or server (see Installation)
• An HTTP client such as curl, httpie, or any language-level HTTP library (e.g., requests for Python, fetch for Node.js)
• Python 3.8 or later if you are running pycli locally
• The base URL of your running pycli instance (e.g., http://localhost:8000)

Follow these steps to install pycli and start the API server locally.

1. Install pycli using pip:

   Copy

   pip install pycli
   

2. Verify the installation:

   Copy

   pycli --version
   

3. Start the API server:

   Copy

   pycli serve
   

   By default the server listens on http://localhost:8000. You should see output confirming the server is running.

4. Confirm the API is reachable:

   Copy

   curl http://localhost:8000/orders
   

   A JSON response indicates the server is ready to accept requests.

The endpoints below accept the following parameters that influence runtime behavior. These are not global config files — they are per-request values you pass as query parameters or in the request body.

Query parameter defaults

Request body fields for POST /orders

Omitting a required field or passing the wrong type causes the API to return a 422 Unprocessable Entity error with a validation detail payload — see Troubleshooting for how to read those errors.

All endpoints follow standard HTTP conventions. The base URL for every request is the address of your running pycli instance (e.g., http://localhost:8000).

List orders

Fetch all orders, optionally narrowing results by status or count:

# Default: returns up to 20 paid orders
curl http://localhost:8000/orders

# Filter by status and restrict to 5 results
curl "http://localhost:8000/orders?status=pending&limit=5"

Create an order

Send a POST request with a JSON body containing at minimum amount and currency:

curl -X POST http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": 250, "currency": "USD"}'

Include the optional note field when you need to attach metadata:

curl -X POST http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": 250, "currency": "USD", "note": "Reorder for project X"}'

View a single order

Replace {order_id} with the integer ID returned when you created the order:

curl http://localhost:8000/orders/42

Cancel an order

Send a DELETE request to the order's URL:

curl -X DELETE http://localhost:8000/orders/42

Cancellation is immediate. There is no confirmation step, so verify the correct order_id before sending the request.

Each example below is self-contained. Run them against a locally running pycli server.

List orders with default parameters

curl http://localhost:8000/orders

Expected response:

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

List pending orders, capped at 5 results

curl "http://localhost:8000/orders?status=pending&limit=5"

Expected response:

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

Create a minimal order

curl -X POST http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "currency": "USD"}'

Expected response:

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

Create an order with an optional note

curl -X POST http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": 500, "currency": "EUR", "note": "Bulk purchase Q4"}'

Expected response:

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

Fetch a single order by ID

curl http://localhost:8000/orders/7

Expected response:

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

Cancel an order

curl -X DELETE http://localhost:8000/orders/7

Expected response:

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

Attempt to create an order with a missing required field (error case)

curl -X POST http://localhost:8000/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": 100}'

Expected response (422 Unprocessable Entity):

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

Use the symptom-cause-fix format below to diagnose common problems.

422 Unprocessable Entity on POST /orders

• Symptom: The API returns HTTP 422 with a detail array.
• Likely cause: Your request body is missing a required field (amount or currency), contains a field of the wrong type (e.g., amount sent as a string instead of an integer), or the Content-Type header is absent.
• Fix: Check the detail array in the response — each entry contains a loc (location of the problem), msg (human-readable description), and type (machine-readable error code). Ensure amount is an integer, currency is a string, and your request includes the header Content-Type: application/json.

422 Unprocessable Entity on GET /orders/{order_id} or DELETE /orders/{order_id}

• Symptom: The API returns HTTP 422 when accessing an order by ID.
• Likely cause: The order_id path segment is not a valid integer (e.g., /orders/abc).
• Fix: Ensure the order ID you are passing is a whole number, not a string or UUID.

GET /orders returns an empty orders array

• Symptom: The response contains "orders": [] even though you expect results.
• Likely cause: The status query parameter defaults to "paid". If your orders have a different status (e.g., "pending" or "canceled"), they will not appear in the default response.
• Fix: Pass the correct status value explicitly: GET /orders?status=pending.

Connection refused when making any request

• Symptom: curl: (7) Failed to connect to localhost port 8000: Connection refused
• Likely cause: The pycli API server is not running, or it started on a different port.
• Fix: Start the server (see Installation) and confirm the port it is listening on. Update your base URL accordingly.

Unexpected null in the response for note

• Symptom: The POST /orders response or a fetched order contains "note": null.
• Likely cause: This is expected behavior. The note field is optional and defaults to null when not provided. The OrderResponse schema does not include note in its output fields at all — this is by design.
• Fix: No action needed. If you require note to be persisted and returned, verify with your API owner whether that field is included in the response schema for your version of pycli.