HTTP is a message protocol: a client sends a method, target, headers, and optional body; a server returns a status, headers, and optional body. JSON is one representation inside those messages. A reliable API contract defines meaning, validation, authorization, errors, retries, and compatibility—not only endpoint names.
The method communicates intent, the path identifies a resource collection, headers carry metadata, and the body carries a representation. HTTPS protects traffic in transit; it does not replace authentication, authorization, or input validation.
A successful creation might return:
Useful statuses include 200, 201, 202, 204, 400, 401, 403, 404, 409, 422, 429, and 503. Do not return 200 for every outcome; machines need meaningful classes of response.
Networks fail ambiguously: a client can miss the response after the server committed the operation. For non-idempotent creation, accept an idempotency key, bind it to the caller and request hash, store the outcome, and return the original result for a true retry. Reject reuse with different input.
Model operations are slow and expensive. Return 202 Accepted with an operation resource for asynchronous work, stream only when useful, and let clients resume from durable run state. A retry must not purchase duplicate model work or execute a tool twice.
Write contracts for create-ticket, get-ticket, and start-AI-draft. Include one forbidden case, one validation error, and one duplicate retry.
Acceptance criteria: another developer can implement a client without asking what each status means or whether retrying duplicates work.