# Tasks

Give your software and AI agents access to real-world execution: structured requests for physical work, carried out by Ryde's provider network and returned with evidence. A Task is its own resource with its own lifecycle — how Ryde staffs it internally is not part of the contract and may change.

Give your software and AI agents access to real-world execution: structured requests for physical work, carried out by Ryde's provider network and returned with evidence. A Task is its own resource with its own lifecycle — how Ryde staffs it internally is not part of the contract and may change.

## Lifecycle

```
  QUOTED
     |
  CREATED
     |
  PROVIDER ASSIGNED     (matched on skill, territory and availability)
     |
  STARTED
     |
  EVIDENCE COLLECTED    (photos with content hashes, capture GPS,
     |                   device timestamps, checklist answers)
  COMPLETED             (or CANCELLED, before work begins)
```

## Operations

### `GET /v1/tasks/types`

The task types this market can actually execute, with the evidence each one collects. Only types Ryde can staff are listed.

- operation: `list_task_types`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_task_types`
- status: planned

```bash
curl -s 'https://sandbox-api.ryde.us.com/v1/tasks/types' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"
```

### `POST /v1/tasks/quote`

Price a task and confirm a qualified provider could be found for it before committing.

- operation: `quote_task`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_task`
- status: planned

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/tasks/quote' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `POST /v1/tasks`

Dispatch real-world work with structured requirements and evidence rules.

- operation: `create_task`
- scope: `tasks.create`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `create_task`
- status: planned

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/tasks' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `GET /v1/tasks/{task_id}`

Task state, the assigned provider, and the evidence collected so far.

- operation: `get_task`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_task`
- status: planned

```bash
curl -s 'https://sandbox-api.ryde.us.com/v1/tasks/$task_id' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"
```

### `GET /v1/tasks/{task_id}/evidence`

The evidence collected against a task: photos with their content hashes, capture GPS and device timestamps, and any checklist answers.

- operation: `get_task_evidence`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_task_evidence`
- status: planned

```bash
curl -s 'https://sandbox-api.ryde.us.com/v1/tasks/$task_id/evidence' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"
```

### `POST /v1/tasks/{task_id}/cancel`

Cancel a task that has not started.

- operation: `cancel_task`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_task`
- status: planned

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/tasks/$task_id/cancel' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```