> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkato.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Raycast API

> Workspace operations for the registered Raycast OAuth client.

The Raycast API lives at `https://api.getkato.io/v1/raycast`. It combines task, record, meeting, activity, and notification operations for the Kato Raycast extension. Its request and response formats differ from the general `/v1` developer API.

## Authentication and visibility

Send an OAuth access token issued to the registered `kato-raycast` client:

```http theme={null}
Authorization: Bearer YOUR_RAYCAST_ACCESS_TOKEN
```

Developer access keys cannot call this surface. Raycast OAuth tokens cannot call the general developer API or CLI API. Use the [OAuth flow](/api-reference/oauth/overview) to understand authorization, refresh, and revocation. Kato currently has no self-service registration endpoint for arbitrary OAuth clients.

Every request rechecks workspace membership. Resource access also respects the member's current role and sharing rules. For example, task lists return tasks assigned to the token owner, while a direct task-detail request can access additional tasks visible to that member. Meeting responses can expose full details, title and time only, or a busy block.

## Start with discovery

* [Inspect identity](/api-reference/raycast/whoami) to confirm the workspace, member, token expiry, and available capabilities.
* [List task statuses](/api-reference/raycast/task-statuses) to resolve workspace-specific status slugs.
* [Get task creation options](/api-reference/raycast/task-options) for valid assignees, record links, sections, and meetings. This endpoint needs all three listed scopes.
* [List objects](/api-reference/raycast/objects) before browsing records by object slug.

## Request and response differences

Raycast task writes use camelCase fields such as `dueDate`, `estimatedTime`, and `linkedRecordIds`. `dueDate` is an ISO 8601 date-time string, rather than the general developer API's millisecond timestamp. Use the separate endpoint pages when moving between surfaces.

Most resources return `{ "data": ... }`. Some discovery endpoints return top-level objects. Paginated collections use `hasMore` and `nextCursor`. Pass the cursor unchanged and keep filters fixed. These are offset-based cursors: concurrent changes can shift results, so deduplicate by ID when traversing a changing list.

Shared [response models](/api-reference/raycast/models) describe tasks, schedule items, record previews, notifications, and search results. Example IDs, statuses, object names, and application URLs are illustrative. Open the returned `webUrl` rather than constructing an application URL yourself.

## Limits and errors

The `/v1` middleware allows **300 requests per minute per key**. On `429`, honor the `Retry-After` header in seconds. Each endpoint specifies its own collection size and required scopes; combined endpoints require every listed scope, even if a search filter selects only one resource type.

`401` indicates an invalid or expired credential; refresh once using the current refresh token. `403` can indicate a wrong token kind, client, scope, or lost membership. `404` can mean a resource is absent or inaccessible. Do not treat an inaccessible task or meeting as permission to retry through another API surface.


## Related topics

- [All endpoints](/api-reference/endpoints.md)
- [Inspect Raycast identity](/api-reference/raycast/whoami.md)
- [OAuth authorization](/api-reference/oauth/overview.md)
- [Developer quickstart](/api-reference/quickstart.md)
- [Raycast](/integrations/raycast.md)