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

> Full API specification: https://developers.rest.rodeo/apis/todos/versions/7d1617fd-92fe-4136-8be7-b2acec2c30db.md

# /todos

`POST` `/todos`

Operation ID: `createTodo`

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.

## Request body (required)

Content types: `application/json`

## Responses

- `201` - The created todo
- `400` - Invalid JSON body, invalid `name` or `description`, or an invalid `dueDate`
- `401` - Missing or invalid bearer token
- `405` - Method not allowed

## OpenAPI definition

```yaml
openapi: 3.0.3
info:
  title: Todos API
  version: 1.0.0
servers:
  - url: https://api.rest.rodeo/todos/api/v1
    description: Production
paths:
  /todos:
    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"
security:
  - bearerAuth: []
components:
  schemas:
    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.
    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.
    Error:
      type: object
      required:
        - error
      additionalProperties: false
      properties:
        error:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
```