---
title: "Make an agent"
method: POST
path: "/v1/agents"
tags: ["agents"]
---

# Make an agent

`POST /v1/agents`

## Request

- Base URL: `https://innernet.live/api`
- URL: `https://innernet.live/api/v1/agents`
- Auth: HTTP bearer

Give an agent a memory of its own. Needs a person's key with the `write` scope; an agent's own key cannot make agents (403). Every setting has a default, so a name is enough. `kind` is `personal` (it works for the person) or `product` (it works for other people, and keeps what it learns about each of them apart from the person's own memory). Mint a key bound to the new agent in the dashboard (agents → the agent → keys): it reaches that agent and nothing else.

## Request body

- object
  - `name` string, required
  - `slug` string: Made from the name when omitted (and numbered if taken). A slug you give that is taken is a 409. `me` is reserved.
  - `kind` 'personal' | 'product': A sub-agent takes its parent's kind; naming another is a 400.
  - `purpose` string
  - `parent` string: The slug or id of one of your top-level agents: make a SUB-AGENT under it. It takes the parent's kind and a copy of its settings (`settings` here changes only what you name), keeps a memory of its own, and gets its own keys; the parent's key does not reach it. Two levels only (a sub-agent cannot have sub-agents: 400), at most 50 under one agent, and your 100 agents count them.
  - `settings` AgentPolicy: An agent's settings: one object, the same in the dashboard and here. Every setting has a default, a PATCH deep-merges into what is there (lists replace), and one wrong setting refuses the whole patch with a sentence naming it.
    - `memory` object: What it keeps.
      - `infer` boolean: Read what it is told into separate memories (one model call), or keep the text as given.
      - `instructions` string: What to keep, in your words.
      - `kinds` string[]: The kinds it keeps; anything else is skipped. Default: all six.
      - `exclude` string[]: Topics it never keeps.
      - `redact` object: Taken out BEFORE anything is stored or sent to a model.
        - `emails` boolean
        - `phones` boolean
        - `secrets` boolean
        - `cards` boolean
      - `retention` object: Days until a memory is deleted (null = never). `run_days` applies to anything with a run_id, `episode_days` to episodes.
        - `default_days` integer, nullable
        - `episode_days` integer, nullable
        - `run_days` integer, nullable
      - `max_memories` integer: Counts earlier versions too: earlier versions go first, then the oldest, least important memories.
      - `dedupe` 'merge' | 'keep': `merge` makes a near-duplicate the next version of the memory it repeats; `keep` keeps both.
    - `person` object: What it learns about the person who owns it, and how much of them it may read.
      - `funnel` 'off' | 'ask' | 'auto': `ask` holds each one for the person's yes, `auto` files it at once, `off` keeps it with the agent.
      - `min_confidence` number: Below this, a memory is kept as the agent's own and never offered.
      - `never` string[]: Personal dimensions it may never file under. Default: relationships, hauntings, kin, somatic.
      - `disclosure` 'private' | 'self' | 'trusted' | 'work': The class floor for anything it files; the fold can only make it more private.
      - `read` 'none' | 'standard' | 'personal' | 'private': How deep into the person's own memory it may read when it recalls with include_person.
    - `recall` object: How it remembers.
      - `limit` integer
      - `threshold` number
      - `rerank` boolean: Re-read the best candidates by meaning (in-process embeddings, nothing stored).
      - `recency` number: How much newer beats older.
      - `include_person` boolean
    - `limits` object
      - `writes_per_minute` integer
      - `reads_per_minute` integer
      - `extract_per_day` integer: 0 turns reading off: a remember with `infer` on answers 400. All of one person's agents also share 20,000 a day.

## Response `201`

Created

- object
  - `agent` Agent
    - `id` string, uuid
    - `slug` string: Unique per person. What you put in the path (or `me`, for the agent a key is bound to).
    - `name` string
    - `kind` 'personal' | 'product': `personal` works for the person; `product` works for other people (it keeps `user_id` memories).
    - `purpose` string, nullable
    - `avatar_url` string, uri, nullable: The picture the person gave this agent in their dashboard, or null (it then wears the mark of the tool it lives in, or its initial). Read only: no request sets it.
    - `status` 'active' | 'paused': A paused agent keeps and recalls nothing (423).
    - `created_via` 'dashboard' | 'api' | 'connection'
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `last_active_at` string, date-time, nullable
    - `parent` string, nullable: The slug of the agent this one works under, or null for a top-level agent. A sub-agent has a memory, keys and settings of its own (it started as a copy of its parent's); two levels only. An agent's own key is never told its parent.
    - `settings` AgentPolicy: An agent's settings: one object, the same in the dashboard and here. Every setting has a default, a PATCH deep-merges into what is there (lists replace), and one wrong setting refuses the whole patch with a sentence naming it.
      - `memory` object: What it keeps.
        - `infer` boolean: Read what it is told into separate memories (one model call), or keep the text as given.
        - `instructions` string: What to keep, in your words.
        - `kinds` string[]: The kinds it keeps; anything else is skipped. Default: all six.
        - `exclude` string[]: Topics it never keeps.
        - `redact` object: Taken out BEFORE anything is stored or sent to a model.
          - `emails` boolean
          - `phones` boolean
          - `secrets` boolean
          - `cards` boolean
        - `retention` object: Days until a memory is deleted (null = never). `run_days` applies to anything with a run_id, `episode_days` to episodes.
          - `default_days` integer, nullable
          - `episode_days` integer, nullable
          - `run_days` integer, nullable
        - `max_memories` integer: Counts earlier versions too: earlier versions go first, then the oldest, least important memories.
        - `dedupe` 'merge' | 'keep': `merge` makes a near-duplicate the next version of the memory it repeats; `keep` keeps both.
      - `person` object: What it learns about the person who owns it, and how much of them it may read.
        - `funnel` 'off' | 'ask' | 'auto': `ask` holds each one for the person's yes, `auto` files it at once, `off` keeps it with the agent.
        - `min_confidence` number: Below this, a memory is kept as the agent's own and never offered.
        - `never` string[]: Personal dimensions it may never file under. Default: relationships, hauntings, kin, somatic.
        - `disclosure` 'private' | 'self' | 'trusted' | 'work': The class floor for anything it files; the fold can only make it more private.
        - `read` 'none' | 'standard' | 'personal' | 'private': How deep into the person's own memory it may read when it recalls with include_person.
      - `recall` object: How it remembers.
        - `limit` integer
        - `threshold` number
        - `rerank` boolean: Re-read the best candidates by meaning (in-process embeddings, nothing stored).
        - `recency` number: How much newer beats older.
        - `include_person` boolean
      - `limits` object
        - `writes_per_minute` integer
        - `reads_per_minute` integer
        - `extract_per_day` integer: 0 turns reading off: a remember with `infer` on answers 400. All of one person's agents also share 20,000 a day.
    - `counts` object: On a list and a single read. What the agent keeps now (current versions, not expired).
      - `memories` integer
      - `users` integer
      - `about_you` object
        - `held` integer
        - `kept` integer
        - `declined` integer
        - `auto` integer

## Other responses

- `400`: Error: a field is wrong; `detail.field` names it, e.g. `parent` when it is not one of your top-level agents (`invalid`)
- `401`: Error
- `403`: Error: an agent key, or a key without `write`, cannot make agents (`forbidden`)
- `409`: Error: that slug is taken, the person already has 100 agents, or the parent already has 50 sub-agents (`conflict`)
- `429`: Error: too many changes at once (`rate_limited`; `Retry-After: 60`)
- `503`: Error: agents are not switched on yet (`unavailable`)

---

[API](https://skmtc.dev/innernet/apis/innernet-api.md) · [All operations](https://skmtc.dev/innernet/apis/innernet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/innernet/apis/innernet-api/revisions/1ee09aec71a9?raw)