---
title: "Create an assistant"
description: "Create an assistant that answers from the resources you give it, from every resource, or from every resource carrying a tag."
canonical: "https://lookio.app/docs/api/assistants/create-assistant"
updated: "2026-10-17"
---

# Create an assistant

Requires `assistants:write`.

Creating an assistant is free. Asking it questions is not: see [Ask an assistant](/docs/api/assistants/query-assistant).

`knowledge` decides what it reads: `all`, `selected` (the `resource_ids`) or `tags` (the `follow_tags`). When you omit it, Lookio infers `tags` if you sent only tags and `selected` otherwise. Send `all` to read every resource.

A resource id that does not exist fails with `resource_not_found`. An API key limited to specific assistants cannot create new ones and gets `permission_denied`.

Send an `Idempotency-Key` header so a retried request does not create two assistants. See [Assistants](/docs/platform/assistants).

```http
POST https://api.lookio.app/v1/assistants
```

## Authorizations

- `Authorization` (bearer, in header, required)

## Header parameters

- `Idempotency-Key` (`string`, length: `1–255 chars`): A unique key for this request, such as a UUID, 1 to 255 visible ASCII characters. Send the same key when you retry: the first response is returned (with `Idempotent-Replayed: true`) instead of running the request again, for 24 hours, per credential. The same key on a different request is a 409 `conflict`. A streamed answer is not recorded.

## Body

`application/json`, required

- `name` (`string`, required, length: `1–120 chars`)
- `context` (`string`, default: `""`, length: `≤ 12000 chars`): What the assistant is and who it talks to: its role and its audience.
- `output_guidelines` (`string`, default: `""`, length: `≤ 12000 chars`): How answers are written: length, format, language.
- `resource_ids` (`string[]`, default: `[]`, items: `≤ 200 items`): The resources it answers from.
- `follow_tags` (`string[]`, items: `≤ 30 items`): Tags it follows when `knowledge` is `tags`: every resource carrying one, now or later, is used (one `knowledge` mode applies at a time).
- `knowledge` (`enum<string>`, one of: `all, selected, tags`): Omit to infer it: `tags` when only tags are given, otherwise `selected`. Send `all` to read every resource.

## Response

**201**: Create an assistant

- `data` (`object`, required)
- `data.id` (`string`, required, pattern: `^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$`)
- `data.name` (`string`, required)
- `data.context` (`string`, required)
- `data.output_guidelines` (`string`, required)
- `data.resource_ids` (`string[]`, required): Empty when this caller may not see the resource catalogue.
- `data.follow_tags` (`string[]`, required)
- `data.knowledge` (`enum<string>`, required, one of: `all, selected, tags`): What the assistant reads: `all` is every resource of the workspace, now and later; `selected` is only `resource_ids`; `tags` is every resource carrying a tag in `follow_tags`, now or later. One mode at a time; the lists of the other modes are kept.
- `data.created_at` (`string`, required)
- `data.updated_at` (`string`, required)
- `request_id` (`string`, required)

```json
{
  "data": {
    "id": "ast_66xcnwtzj8vt",
    "name": "Support",
    "context": "You are the support assistant of Acme. You answer customers who want a quick, accurate reply.",
    "output_guidelines": "Short answers, in the language of the question.",
    "resource_ids": [
      "res_thk6smb5nvts"
    ],
    "follow_tags": [],
    "knowledge": "selected",
    "created_at": "2026-10-12T09:30:00.000Z",
    "updated_at": "2026-10-12T09:30:00.000Z"
  },
  "request_id": "req_01K9X7M2Q4"
}
```

**400**: Possible codes: invalid_request, unknown_field, invalid_parameter, invalid_cursor

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**401**: Possible codes: authentication_required, invalid_api_key, api_key_expired, api_key_revoked, invalid_access_key

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**403**: Possible codes: insufficient_scope, feature_not_available, admin_required, permission_denied

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**404**: Possible codes: resource_not_found

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**409**: Possible codes: conflict, assistant_has_no_resources

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**413**: Possible codes: request_too_large

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**429**: Possible codes: rate_limited

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**500**: Possible codes: internal_error

- `error` (`object`, required)
- `error.type` (`string`, required)
- `error.code` (`string`, required)
- `error.message` (`string`, required)
- `error.param` (`string`)
- `error.docs_url` (`string`, required)
- `error.action_url` (`string<uri>`)
- `request_id` (`string`, required)

```json
{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}
```

**Example request**

```bash
curl --request POST \
  --url 'https://api.lookio.app/v1/assistants' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>"
}'
```