---
title: "Change an agent"
method: PATCH
path: "/v1/agents/{agent}"
tags: ["agents"]
---

# Change an agent

`PATCH /v1/agents/{agent}`

## Request

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

Rename it, change its purpose, pause it (`status: "paused"`: it keeps and recalls nothing, and answers 423, until `active`) or change its settings. `settings` is the same object the dashboard shows and it DEEP-MERGES into the current one (lists replace); one wrong setting refuses the whole patch and nothing is half-applied. Needs a person's key with `write`; an agent key answers 403.

## Path parameters

- `agent` string, required

## Request body

- object
  - `name` string
  - `purpose` string, nullable
  - `kind` 'personal' | 'product'
  - `status` 'active' | 'paused'
  - `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 `200`

OK

- 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 or a setting is wrong; `detail.field` names it, e.g. `recall.limit` (`invalid`)
- `401`: Error
- `403`: Error: an agent key, or a key without `write` (`forbidden`)
- `404`: Error: no such agent for this key (`not_found`)
- `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)