Getting Started

This page walks you through making your first request to the pycli HTTP API. By the end, you will have installed pycli, sent a real HTTP request to create an order, and understood the response you get back. Getting this baseline working quickly means you can move on to deploying stacks, managing configuration, and building order workflows with confidence.

Before you begin, make sure you have the following in place:

• Python — pycli is a Python project; ensure you have a supported Python installation available.
• curl — the examples on this page use curl to send HTTP requests. Any HTTP client works, but the commands shown assume curl is available in your terminal.
• Network access to the API — the API base URL used throughout this page is https://api.example.com. Replace this with your actual deployed endpoint.
• A running pycli API server — the FastAPI app must be running and reachable before you can make requests. If you are hosting it yourself, confirm the server started without errors.

The fastest path to a working API request is to create an order. The following steps take you from nothing to a successful 201 Created response.

1. Confirm the API is reachable:

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

2. Send your first POST request to create an order:

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

3. Note the order_id in the response — you will use it to retrieve or cancel the order in subsequent steps.

Follow these steps to work through the core API workflows in order.

Step 1 — List existing orders

Before creating anything, confirm the API is responding by listing current orders. This request requires no body.

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

Success looks like an HTTP 200 OK response with a JSON array of orders (which may be empty if no orders exist yet).

Step 2 — Create an order

Send a POST request to /orders with a JSON body containing the amount (integer) and currency (string) fields. The Content-Type: application/json header tells the server to parse the body as JSON.

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

Success returns a response containing the newly created order, including an order_id you can use in subsequent requests.

Step 3 — Retrieve a single order

Use the order_id from Step 2 to fetch that specific order. Replace 42 with your actual ID.

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

Success returns a 200 OK response with the order details as a JSON object.

Step 4 — Filter orders by status

You can narrow the list of orders by passing query parameters. For example, to retrieve only paid orders and limit the results:

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

Success returns a 200 OK response with a filtered JSON array.

Step 5 — Cancel an order

Send a DELETE request to /orders/{order_id} to cancel a specific order. Replace 42 with the ID of the order you want to cancel.

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

Success returns a response confirming the order has been cancelled.

The examples below are self-contained and runnable. Replace https://api.example.com with your actual base URL and replace order IDs with real values from your environment.

Create an order

POST a new order with an amount of 1500 in USD.

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

Fetch a single order

Retrieve the order with ID 42.

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

List paid orders (with a limit)

Filter the order list to only paid orders, returning at most 10 results.

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

Cancel an order

Delete the order with ID 42.

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

Use the following table to diagnose common problems when getting started.

Symptom: curl: (6) Could not resolve host: api.example.com

Likely cause: The base URL is wrong or your network cannot reach the server.

Fix: Replace api.example.com with your actual deployed API hostname. Verify the server is running and reachable from your network. If you are running the API locally, use http://localhost:<port> instead.

Symptom: HTTP 422 Unprocessable Entity when creating an order

Likely cause: The request body is missing a required field or a field has the wrong type. The API validates the body against a defined schema — amount must be an integer and currency must be a string.

Fix: Ensure your request body includes both amount (integer) and currency (string), and that the Content-Type: application/json header is present. Example of a valid body: {"amount": 1500, "currency": "USD"}.

Symptom: HTTP 404 Not Found when fetching or cancelling an order

Likely cause: The order_id in your URL does not match any existing order.

Fix: Confirm the order ID by listing all orders first with GET /orders, then use an ID from that response.

Symptom: HTTP 405 Method Not Allowed

Likely cause: You sent an HTTP method that the endpoint does not support (for example, sending DELETE to /orders instead of /orders/{order_id}).

Fix: Check the endpoint path and method. The supported methods are: POST /orders, GET /orders, GET /orders/{order_id}, and DELETE /orders/{order_id}.