---
title: "Todos API"
url: "https://developers.rest.rodeo/apis/todos/versions/7d1617fd-92fe-4136-8be7-b2acec2c30db"
---

# Todos API

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Todos API","description":"Manages todos. The billing profile is usage-based: every Todo created costs $0.01 USD. Usage is recorded per created Todo in an append-only ledger and invoiced monthly, per calendar month (UTC). Reads, updates, and deletes are not billable. A Todo starts out incomplete; `completedAt` is set by the server when `completed` flips to true and cleared when it flips back to false.","version":"1.0.0"},"servers":[{"url":"https://api.rest.rodeo/todos/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/todos":{"get":{"operationId":"listTodos","summary":"/todos","description":"Lists every todo.","responses":{"200":{"description":"All todos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodosList"},"examples":{"todos":{"value":{"todos":[{"id":"1f6e4c8a-2b3c-4d0f-9b0d-c7f2b6de4b1a","name":"Book the rodeo","description":"Reserve seats for the weekend show.","dueDate":"2026-10-15T17:00:00.000Z","completed":false,"createdAt":"2026-09-29T09:12:00.000Z","updatedAt":"2026-09-29T09:12:00.000Z","completedAt":null}]}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createTodo","summary":"/todos","description":"Creates a todo. The todo starts out incomplete and the server sets `createdAt` and `updatedAt`. Creating a todo is a billable event charged at $0.01 USD.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodoRequest"},"examples":{"create":{"value":{"name":"Book the rodeo","description":"Reserve seats for the weekend show.","dueDate":"2026-10-15T17:00:00.000Z"}}}}}},"responses":{"201":{"description":"The created todo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Todo"},"examples":{"todo":{"value":{"id":"1f6e4c8a-2b3c-4d0f-9b0d-c7f2b6de4b1a","name":"Book the rodeo","description":"Reserve seats for the weekend show.","dueDate":"2026-10-15T17:00:00.000Z","completed":false,"createdAt":"2026-09-29T09:12:00.000Z","updatedAt":"2026-09-29T09:12:00.000Z","completedAt":null}}}}}},"400":{"description":"Invalid JSON body, invalid `name` or `description`, or an invalid `dueDate`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/todos/{todoId}":{"get":{"operationId":"getTodo","summary":"/todos/{todoId}","description":"Returns a single todo by id.","parameters":[{"$ref":"#/components/parameters/TodoId"}],"responses":{"200":{"description":"The todo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Todo"},"examples":{"todo":{"value":{"id":"1f6e4c8a-2b3c-4d0f-9b0d-c7f2b6de4b1a","name":"Book the rodeo","description":"Reserve seats for the weekend show.","dueDate":"2026-10-15T17:00:00.000Z","completed":true,"createdAt":"2026-09-29T09:12:00.000Z","updatedAt":"2026-09-29T10:00:00.000Z","completedAt":"2026-09-29T10:00:00.000Z"}}}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No todo with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateTodo","summary":"/todos/{todoId}","description":"Replaces the todo's `name`, `description`, and `dueDate`. Omitting `dueDate` clears it. Optionally toggles `completed`; the server sets `completedAt` to the update time when the todo flips to complete and clears it when it flips back to incomplete. Bumps `updatedAt` to the update time.","parameters":[{"$ref":"#/components/parameters/TodoId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodoUpdateRequest"},"examples":{"update":{"value":{"name":"Book the rodeo","description":"Seats are reserved for the weekend show.","dueDate":"2026-10-16T17:00:00.000Z","completed":true}}}}}},"responses":{"200":{"description":"The updated todo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Todo"},"examples":{"todo":{"value":{"id":"1f6e4c8a-2b3c-4d0f-9b0d-c7f2b6de4b1a","name":"Book the rodeo","description":"Seats are reserved for the weekend show.","dueDate":"2026-10-16T17:00:00.000Z","completed":true,"createdAt":"2026-09-29T09:12:00.000Z","updatedAt":"2026-09-29T10:00:00.000Z","completedAt":"2026-09-29T10:00:00.000Z"}}}}}},"400":{"description":"Invalid JSON body, invalid `name` or `description`, or an invalid `dueDate`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No todo with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteTodo","summary":"/todos/{todoId}","description":"Deletes the todo. Deleting a todo is not billable and does not remove previously recorded usage.","parameters":[{"$ref":"#/components/parameters/TodoId"}],"responses":{"204":{"description":"The todo was deleted"},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No todo with this id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"TodoId":{"name":"todoId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The todo id."}},"schemas":{"Todo":{"type":"object","required":["id","name","description","dueDate","completed","createdAt","updatedAt","completedAt"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The todo id."},"name":{"type":"string","description":"The todo name.","maxLength":256,"minLength":1},"description":{"type":"string","description":"The todo description.","maxLength":2000},"dueDate":{"type":"string","format":"date-time","nullable":true,"description":"When the todo is due, or null when it has no due date."},"completed":{"type":"boolean","description":"Whether the todo has been completed."},"createdAt":{"type":"string","format":"date-time","description":"When the todo was created. This is the billable event."},"updatedAt":{"type":"string","format":"date-time","description":"When the todo was last updated."},"completedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the todo was completed, or null while it is incomplete."}}},"TodoRequest":{"type":"object","required":["name","description"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The todo name.","maxLength":256,"minLength":1},"description":{"type":"string","description":"The todo description.","maxLength":2000},"dueDate":{"type":"string","format":"date-time","description":"When the todo is due. Optional; omit or send null for no due date."}}},"TodoUpdateRequest":{"type":"object","required":["name","description"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The todo name.","maxLength":256,"minLength":1},"description":{"type":"string","description":"The todo description.","maxLength":2000},"dueDate":{"type":"string","format":"date-time","description":"When the todo is due. Optional; omitting it clears the due date."},"completed":{"type":"boolean","description":"Whether the todo has been completed. Optional; omitting it leaves the completion state unchanged."}}},"TodosList":{"type":"object","required":["todos"],"additionalProperties":false,"properties":{"todos":{"type":"array","items":{"$ref":"#/components/schemas/Todo"}}}},"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string"}}}}}}
```