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

# Agent URL and ports

> Read a hosted agent's URL, set its default port and exposed ports, and issue port tokens.

Paths are relative to `https://inkbox.ai/api/v1/identities/my-agent`. Authenticate with an API key in `X-API-Key`. Any key that can [read hosting](https://inkbox.ai/docs/api/identities/hosting.md#read-hosting) can read ports, including the identity's own agent-scoped key. Changing ports or rotating tokens needs an admin-scoped key; agent-scoped keys get `403`. In the Console, any organization member can view ports and admins can change them. The identity must be a [hosted agent](https://inkbox.ai/docs/capabilities/hosted-agents.md); otherwise these endpoints return `409` with code `identity_not_hosted`.

For how addresses, tokens, and public ports behave, see [Agent URLs](https://inkbox.ai/docs/capabilities/agent-urls.md).

## Response

All three endpoints return the agent's address:

```json theme={null}
{
  "url": "https://my-agent.inkbox.sh",
  "default_port": 3000,
  "version": 7,
  "ports": [
    {
      "port": 3000,
      "public": false,
      "url": "https://my-agent--3000.inkbox.sh",
      "token_url": null
    },
    {
      "port": 8080,
      "public": true,
      "url": "https://my-agent--8080.inkbox.sh",
      "token_url": null
    }
  ]
}
```

| Field | Meaning |
| - | - |
| `url` | The agent's base address. Serves `default_port`. |
| `default_port` | Port served at `url`, or `null`. |
| `version` | Changes whenever the ports, their access, their tokens, or the default port change. Starting or stopping the computer doesn't change it. Send it back with `PATCH` to avoid overwriting someone else's change. |
| `ports` | Exposed ports. |
| `ports[].public` | `true` when anyone can reach the port without a token. |
| `ports[].url` | The port's own address, or `null` when the handle is longer than 56 characters. |
| `ports[].token_url` | Shareable link with the port token. Returned only in the response that creates the token. |

## Read ports

`GET /hosting/ports`

## Update ports

`PATCH /hosting/ports`

```json theme={null}
{
  "version": 7,
  "default_port": 3000,
  "ports": [
    {"port": 3000, "public": false},
    {"port": 8080, "public": true}
  ]
}
```

| Field | Type | Description |
| - | - | - |
| `version` | integer | `version` from your last read. If the ports changed since, returns `409` with code `stale_version`; read again and retry. |
| `default_port` | integer \| null | Port served at the base address. Must be in `ports`. Send `null` to clear it. Omit to keep it. To remove the default port from `ports`, send `"default_port": null` in the same request. |
| `ports` | array | Full list of exposed ports, up to 32, each listed once. Replaces the current list. Omit to keep it. |
| `ports[].port` | integer | `1` to `65535`. |
| `ports[].public` | boolean | Defaults to `false`. |

> [!WARNING]
>
> `ports` replaces the whole list. Any port you leave out is removed, along with its token. To change one port, read the current list, edit it, and send the full list back.

Ports you keep keep their tokens. Removing a port deletes its token. When you add a private port, the response includes its `token_url` once; store it. Later reads return `null`, and [rotating](#rotate-a-port-token) issues a new link.

## Rotate a port token

`POST /hosting/ports/{port}/token`

Issues a new token for an exposed port and returns the address with that port's `token_url`. The previous token stops working immediately. Store `token_url`: later reads return `null`.

```bash theme={null}
curl -X POST https://inkbox.ai/api/v1/identities/my-agent/hosting/ports/3000/token \
  -H "X-API-Key: $INKBOX_API_KEY"
```

Returns `404` if the port isn't exposed.

## SDKs and CLI

```python Python theme={null}
ports = client.identities.get_hosting_ports("my-agent")

ports = client.identities.update_hosting_ports("my-agent", {
    "version": ports.version,
    "default_port": 3000,
    "ports": [{"port": 3000, "public": False}, {"port": 8080, "public": True}],
})

ports = client.identities.rotate_hosting_port_token("my-agent", 3000)
print(next(p for p in ports.ports if p["port"] == 3000)["token_url"])
```

```typescript TypeScript theme={null}
let ports = await inkbox.identities.getHostingPorts("my-agent");

ports = await inkbox.identities.updateHostingPorts("my-agent", {
  version: ports.version,
  defaultPort: 3000,
  ports: [{ port: 3000, public: false }, { port: 8080, public: true }],
});

ports = await inkbox.identities.rotateHostingPortToken("my-agent", 3000);
console.log(ports.ports.find((p) => p.port === 3000)?.tokenUrl);
```

```bash CLI theme={null}
inkbox identity hosting ports show my-agent
inkbox identity hosting ports set my-agent 3000 --private
inkbox identity hosting ports set my-agent 8080 --public
inkbox identity hosting ports default my-agent 3000
inkbox identity hosting ports rotate-token my-agent 3000
```

`update_hosting_ports` and `updateHostingPorts` send `PATCH /hosting/ports`, so `ports` replaces the whole list. Omit `ports` to change only the default port. In the CLI, `ports set` adds the port or changes its access and keeps the other ports, sending the version it read and retrying once if the ports changed meanwhile; `ports default <handle> none` clears the default port.

## Read the base URL

[`GET /hosting`](https://inkbox.ai/docs/api/identities/hosting#read-hosting) also returns `url`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.