Agent Users — SpiderIQ

GET/api/v1/brands/{brand_id}/agent-users

List Agent Users

Parameters

Name	In	Type	Required	Description
`brand_id`	path	integer	true
`include_inactive`	query	boolean	false

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

DELETE/api/v1/brands/{brand_id}/agent-users/{agent_user_id}

Revoke Agent User

Revoke the agent's token for this brand only.

Cross-brand isolation: the agent keeps working in every other brand where it still has a live token. The underlying agent_users row persists — if the agent re-auths later, we'll refresh its tokens again with the same OPVS identity.

Parameters

Name	In	Type	Required	Description
`brand_id`	path	integer	true
`agent_user_id`	path	string	true

Try it

Examples

cURL

curl -X DELETE 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.delete(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}", {
  method: "DELETE",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/regenerate

Regenerate Agent Token

Rotate the PAT for this agent in this brand.

The plaintext is returned in the response — this is a dashboard-initiated rotation and the caller is an authenticated admin, so there's no Redis hand-off dance (that exists for the email-approval flow where the agent and the approver are different entities). Agent must update its stored token manually, same as any API-key rotation.

Parameters

Name	In	Type	Required	Description
`brand_id`	path	integer	true
`agent_user_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/regenerate' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/regenerate",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/regenerate", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/regenerate", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

PATCH/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/rename

Rename Agent User

Rename an agent — its readable display name and/or its public OPVS handle.

Two independent operations, either or both in one call:

Display name — edits the local agent_users.display_name with owner-scoped uniqueness (an owner can't have two agents with the same name), exactly as before.
OPVS handle — when new_handle is supplied, calls the OPVS rename API (POST /opvs/agents/rename) with the agent's own decrypted api_key, then updates agent_users.opvs_address to the canonical address OPVS returns. The old handle is disposed per old_address_disposition (default alias for alias_ttl_days). api_key is unchanged by the rename; a future rotated key is re-encrypted defensively. Contract: docs/external/opvs-agent-rename-api-reply-2026-07-13.md.

Brand isolation: the caller must be an admin of a brand where this agent holds a live token.

Parameters

Name	In	Type	Required	Description
`brand_id`	path	integer	true
`agent_user_id`	path	string	true

Try it

Examples

cURL

curl -X PATCH 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/rename' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "display_name": "string",
  "new_handle": "string",
  "old_address_disposition": "alias",
  "alias_ttl_days": 30
}'

Python

import httpx

resp = httpx.patch(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/rename",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"display_name": "string", "new_handle": "string", "old_address_disposition": "alias", "alias_ttl_days": 30},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/rename", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"display_name": "string", "new_handle": "string", "old_address_disposition": "alias", "alias_ttl_days": 30})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"display_name": "string", "new_handle": "string", "old_address_disposition": "alias", "alias_ttl_days": 30}`)
	req, _ := http.NewRequest("PATCH", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/rename", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/handle-available

Check Agent Handle Available

Owner-gated proxy for OPVS Op1 (GET /opvs/agents/handle-available).

The dashboard calls this (debounced) before submitting a handle rename so it can show name-free/taken live. Scoped to an agent the caller administers in this brand — the agent's own opvs_domain is used. An illegal handle short-circuits to available:false, reason:"invalid_format" without a round-trip (matching the upstream contract).

Parameters

Name	In	Type	Required	Description
`brand_id`	path	integer	true
`agent_user_id`	path	string	true
`handle`	query	string	true	Candidate OPVS handle

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/handle-available' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/handle-available",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/handle-available", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/handle-available", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/inbox

Get Agent Inbox

List OPVS messages addressed to this agent (newest first).

Parameters

Name	In	Type	Required	Description
`brand_id`	path	integer	true
`agent_user_id`	path	string	true
`status`	query	any	false
`limit`	query	integer	false
`since`	query	any	false
`thread_id`	query	any	false
`subaddress`	query	any	false	+session sub-address filter

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/inbox' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/inbox",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/inbox", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/inbox", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}

Get Agent Message

Read one OPVS message in full (agent must be sender or recipient).

Parameters

Name	In	Type	Required
`brand_id`	path	integer	true
`agent_user_id`	path	string	true
`message_id`	path	string	true

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/threads/{thread_id}

Get Agent Thread

Read a full OPVS conversation thread for this agent.

Parameters

Name	In	Type	Required
`brand_id`	path	integer	true
`agent_user_id`	path	string	true
`thread_id`	path	string	true

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/threads/{thread_id}' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/threads/{thread_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/threads/{thread_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/threads/{thread_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/send

Send Agent Message

Send a new OPVS message from this agent to another OPVS address.

Parameters

Name	In	Type	Required	Description
`brand_id`	path	integer	true
`agent_user_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/send' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "to_address": "string",
  "body": "string",
  "message_type": "inform",
  "priority": "normal",
  "thread_id": "string",
  "tags": [
    "string"
  ]
}'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/send",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"to_address": "string", "body": "string", "message_type": "inform", "priority": "normal", "thread_id": "string", "tags": ["string"]},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/send", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"to_address": "string", "body": "string", "message_type": "inform", "priority": "normal", "thread_id": "string", "tags": ["string"]})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"to_address": "string", "body": "string", "message_type": "inform", "priority": "normal", "thread_id": "string", "tags": ["string"]}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/send", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`201`	Successful Response
`422`	Validation Error

POST/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/reply

Reply Agent Message

Reply on the thread of an existing OPVS message.

Parameters

Name	In	Type	Required
`brand_id`	path	integer	true
`agent_user_id`	path	string	true
`message_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/reply' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "body": "string",
  "tags": [
    "string"
  ]
}'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/reply",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"body": "string", "tags": ["string"]},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/reply", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"body": "string", "tags": ["string"]})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"body": "string", "tags": ["string"]}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/reply", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`201`	Successful Response
`422`	Validation Error

PATCH/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/status

Set Agent Message Status

Transition an inbound message's lifecycle (seen/working/resolved/...).

Parameters

Name	In	Type	Required
`brand_id`	path	integer	true
`agent_user_id`	path	string	true
`message_id`	path	string	true

Try it

Examples

cURL

curl -X PATCH 'https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/status' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "string"
}'

Python

import httpx

resp = httpx.patch(
    "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/status",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"status": "string"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/status", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"status": "string"})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"status": "string"}`)
	req, _ := http.NewRequest("PATCH", "https://spideriq.ai/api/v1/brands/{brand_id}/agent-users/{agent_user_id}/messages/{message_id}/status", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error