Nova Admin Docs

API Reference

The Nova Admin REST API surface, generated from the OpenAPI 3.1 spec. 85 operations across 14 resource groups.

This page is generated from the OpenAPI 3.1 specification at src/lib/openapi. The live machine-readable spec is served at GET /api/v1/openapi. There are 85 operations across 14 resource groups.

Base URL

https://admin.example.com

Authentication

Every endpoint requires authentication. Two mechanisms are accepted:

  • Session cookie (admin-session) — Firebase Auth session for browser/dashboard callers.
  • API key — Authorization: Bearer <key> for programmatic callers. See Authentication for scopes.

Auth

Authentication and session management

MethodPathSummary
DELETE/api/v1/auth/sessionLogout
GET/api/v1/auth/sessionVerify session
POST/api/v1/auth/sessionCreate session cookie

Agents

Agent CRUD, configuration, and status

MethodPathSummary
GET/api/v1/agentsList all agents
POST/api/v1/agentsCreate agent
DELETE/api/v1/agents/{id}Delete agent (soft)
GET/api/v1/agents/{id}Get agent
PATCH/api/v1/agents/{id}Update agent
GET/api/v1/agents/healthSystem health
GET/api/v1/agents/memoryList memories
POST/api/v1/agents/memoryCreate memory
GET/api/v1/agents/modelsList Claude models
GET/api/v1/agents/toolsList tool categories

POST /api/v1/agents

Create agent

Request body (application/json)

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "displayName": {
      "type": "string"
    }
  },
  "required": [
    "name",
    "displayName"
  ]
}

DELETE /api/v1/agents/{id}

Delete agent (soft)

Parameters

NameInRequiredType
idpathyesstring

GET /api/v1/agents/{id}

Get agent

Parameters

NameInRequiredType
idpathyesstring

PATCH /api/v1/agents/{id}

Update agent

Parameters

NameInRequiredType
idpathyesstring

Skills

Skill management for agents

MethodPathSummary
GET/api/v1/agents/skillsList skills
POST/api/v1/agents/skillsCreate skill
DELETE/api/v1/agents/skills/{id}Delete skill
GET/api/v1/agents/skills/{id}Get skill
PATCH/api/v1/agents/skills/{id}Update skill

DELETE /api/v1/agents/skills/{id}

Delete skill

Parameters

NameInRequiredType
idpathyesstring

GET /api/v1/agents/skills/{id}

Get skill

Parameters

NameInRequiredType
idpathyesstring

PATCH /api/v1/agents/skills/{id}

Update skill

Parameters

NameInRequiredType
idpathyesstring

Flows

Automation flow configuration and execution

MethodPathSummary
GET/api/v1/agents/flowsList flows
POST/api/v1/agents/flowsCreate flow
DELETE/api/v1/agents/flows/{id}Delete flow
GET/api/v1/agents/flows/{id}Get flow
PATCH/api/v1/agents/flows/{id}Update flow
POST/api/v1/agents/flows/{id}/triggerTrigger flow

DELETE /api/v1/agents/flows/{id}

Delete flow

Parameters

NameInRequiredType
idpathyesstring

GET /api/v1/agents/flows/{id}

Get flow

Parameters

NameInRequiredType
idpathyesstring

PATCH /api/v1/agents/flows/{id}

Update flow

Parameters

NameInRequiredType
idpathyesstring

POST /api/v1/agents/flows/{id}/trigger

Trigger flow

Parameters

NameInRequiredType
idpathyesstring

Threads

Conversation threads and messages

MethodPathSummary
POST/api/v1/chatSend chat message
GET/api/v1/threadsList threads
POST/api/v1/threadsCreate thread
DELETE/api/v1/threads/{id}Delete thread
GET/api/v1/threads/{id}Get thread
PATCH/api/v1/threads/{id}Update thread
DELETE/api/v1/threads/{id}/accessRemove thread access entries
GET/api/v1/threads/{id}/accessGet thread access state
PATCH/api/v1/threads/{id}/accessUpdate thread access settings
POST/api/v1/threads/{id}/accessCreate thread access entries
POST/api/v1/threads/{id}/forkFork thread
GET/api/v1/threads/{id}/messagesGet messages
GET/api/v1/threads/statsThread stats

GET /api/v1/threads

List threads

Parameters

NameInRequiredType
statusquerynostring
sourcequerynostring
limitquerynointeger

DELETE /api/v1/threads/{id}

Delete thread

Parameters

NameInRequiredType
idpathyesstring

GET /api/v1/threads/{id}

Get thread

Parameters

NameInRequiredType
idpathyesstring

PATCH /api/v1/threads/{id}

Update thread

Parameters

NameInRequiredType
idpathyesstring

DELETE /api/v1/threads/{id}/access

Remove thread access entries

Parameters

NameInRequiredType
idpathyesstring

GET /api/v1/threads/{id}/access

Get thread access state

Parameters

NameInRequiredType
idpathyesstring

PATCH /api/v1/threads/{id}/access

Update thread access settings

Parameters

NameInRequiredType
idpathyesstring

POST /api/v1/threads/{id}/access

Create thread access entries

Parameters

NameInRequiredType
idpathyesstring

POST /api/v1/threads/{id}/fork

Fork thread

Parameters

NameInRequiredType
idpathyesstring

GET /api/v1/threads/{id}/messages

Get messages

Parameters

NameInRequiredType
idpathyesstring

Users

Nova main user lookup and details (BigQuery)

MethodPathSummary
GET/api/v1/usersList users (paginated)
GET/api/v1/users/{userId}Get user
GET/api/v1/users/{userId}/stripeUser Stripe data
GET/api/v1/users/{userId}/timelineUser timeline
GET/api/v1/users/{userId}/websitesUser websites

GET /api/v1/users

List users (paginated)

Parameters

NameInRequiredType
limitquerynointeger
statusquerynostring
searchquerynostring

GET /api/v1/users/{userId}

Get user

Parameters

NameInRequiredType
userIdpathyesstring

GET /api/v1/users/{userId}/stripe

User Stripe data

Parameters

NameInRequiredType
userIdpathyesstring

GET /api/v1/users/{userId}/timeline

User timeline

Parameters

NameInRequiredType
userIdpathyesstring

GET /api/v1/users/{userId}/websites

User websites

Parameters

NameInRequiredType
userIdpathyesstring

Nova Users

Admin user management (Firestore)

MethodPathSummary
GET/api/v1/nova-usersList admin users
POST/api/v1/nova-usersCreate admin user
GET/api/v1/nova-users/{id}Get admin user
POST/api/v1/nova-users/{id}/deactivateDeactivate
POST/api/v1/nova-users/{id}/reactivateReactivate

GET /api/v1/nova-users/{id}

Get admin user

Parameters

NameInRequiredType
idpathyesstring

POST /api/v1/nova-users/{id}/deactivate

Deactivate

Parameters

NameInRequiredType
idpathyesstring

POST /api/v1/nova-users/{id}/reactivate

Reactivate

Parameters

NameInRequiredType
idpathyesstring

Analytics

Overview, traffic, revenue, and product analytics

MethodPathSummary
GET/api/v1/analytics/insightsAI insights
GET/api/v1/analytics/overviewOverview metrics
GET/api/v1/analytics/product/active-usersActive users
GET/api/v1/analytics/product/cohort-retentionCohort retention
GET/api/v1/analytics/product/feature-adoptionFeature adoption
GET/api/v1/analytics/product/onboarding-funnelOnboarding funnel
GET/api/v1/analytics/product/website-statesWebsite states
GET/api/v1/analytics/revenue/churnChurn data
GET/api/v1/analytics/revenue/ltvLTV data
GET/api/v1/analytics/revenue/mrrMRR data
GET/api/v1/analytics/revenue/subscriptionsSubscriptions
GET/api/v1/analytics/traffic/channelsTraffic by channel
GET/api/v1/analytics/traffic/geographyGeographic traffic
GET/api/v1/analytics/traffic/technologyTechnology breakdown
GET/api/v1/analytics/traffic/visitorsVisitor traffic

Reports

Report creation and management

MethodPathSummary
GET/api/v1/reportsList reports
POST/api/v1/reportsCreate report
DELETE/api/v1/reports/{id}Delete report
GET/api/v1/reports/{id}Get report
PATCH/api/v1/reports/{id}Update report

DELETE /api/v1/reports/{id}

Delete report

Parameters

NameInRequiredType
idpathyesstring

GET /api/v1/reports/{id}

Get report

Parameters

NameInRequiredType
idpathyesstring

PATCH /api/v1/reports/{id}

Update report

Parameters

NameInRequiredType
idpathyesstring

Settings

Bot configuration and admin settings

MethodPathSummary
GET/api/v1/bot-configGet bot config
PUT/api/v1/bot-configUpdate bot config
GET/api/v1/settingsAdmin settings
PATCH/api/v1/settingsUpdate settings

PUT /api/v1/bot-config

Update bot config

Request body (application/json)

{
  "$ref": "#/components/schemas/BotConfigUpdate"
}

System

Health checks and system status

MethodPathSummary
GET/api/v1/healthHealth check
GET/api/v1/searchGlobal search

GET /api/v1/search

Global search

Parameters

NameInRequiredType
qqueryyesstring

MCP

Nova unified MCP endpoint — JSON-RPC 2.0 over HTTP, api-key authenticated. One URL serves every resource type (integration tools, agents, flows, projects, tasks, goals, documents, artifacts, memory) with caller-visibility gated by api-key grants.

MethodPathSummary
GET/api/v1/mcpEndpoint health stub
POST/api/v1/mcpNova unified MCP endpoint — JSON-RPC 2.0

POST /api/v1/mcp

Nova unified MCP endpoint — JSON-RPC 2.0

Request body (application/json)

{
  "type": "object",
  "required": [
    "jsonrpc",
    "method"
  ],
  "properties": {
    "jsonrpc": {
      "type": "string",
      "enum": [
        "2.0"
      ]
    },
    "id": {
      "description": "Request id. Omit for notifications.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        }
      ]
    },
    "method": {
      "type": "string",
      "enum": [
        "initialize",
        "tools/list",
        "tools/call"
      ]
    },
    "params": {
      "type": "object"
    }
  }
}

Capsules

Named bundles of allowed tools exposed as bearer-authenticated MCP endpoints for BYO-LLM clients (Claude Desktop, Cursor, custom code). Nova provides auth + audit; the client provides the model.

MethodPathSummary
GET/api/capsulesList capsules
POST/api/capsulesCreate a capsule
DELETE/api/capsules/{id}Delete a capsule
GET/api/capsules/{id}Get a capsule
PATCH/api/capsules/{id}Update a capsule
POST/api/capsules/{id}/rotate-tokenRotate the bearer token

POST /api/capsules

Create a capsule

Request body (application/json)

{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 120
    },
    "description": {
      "type": "string",
      "maxLength": 2000
    },
    "allowedTools": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "deniedTools": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "live",
        "disabled"
      ]
    }
  }
}

DELETE /api/capsules/{id}

Delete a capsule

Parameters

NameInRequiredType
idpathyesstring

GET /api/capsules/{id}

Get a capsule

Parameters

NameInRequiredType
idpathyesstring

PATCH /api/capsules/{id}

Update a capsule

Parameters

NameInRequiredType
idpathyesstring

POST /api/capsules/{id}/rotate-token

Rotate the bearer token

Parameters

NameInRequiredType
idpathyesstring

Versions

Generic version history, diff, and restore surfaces for versioned Nova entities.

MethodPathSummary
GET/api/v1/versions/{entityType}/{entityId}List versions for an entity
GET/api/v1/versions/{entityType}/{entityId}/{versionId}Get a version
GET/api/v1/versions/{entityType}/{entityId}/{versionId}/diffDiff a version
POST/api/v1/versions/{entityType}/{entityId}/{versionId}/restoreRestore an entity to a version

GET /api/v1/versions/{entityType}/{entityId}

List versions for an entity

Parameters

NameInRequiredType
entityTypepathyesstring
entityIdpathyesstring

GET /api/v1/versions/{entityType}/{entityId}/{versionId}

Get a version

Parameters

NameInRequiredType
entityTypepathyesstring
entityIdpathyesstring
versionIdpathyesstring

GET /api/v1/versions/{entityType}/{entityId}/{versionId}/diff

Diff a version

Parameters

NameInRequiredType
entityTypepathyesstring
entityIdpathyesstring
versionIdpathyesstring
againstqueryno

POST /api/v1/versions/{entityType}/{entityId}/{versionId}/restore

Restore an entity to a version

Parameters

NameInRequiredType
entityTypepathyesstring
entityIdpathyesstring
versionIdpathyesstring

Request body (application/json)

{
  "type": "object",
  "properties": {
    "expectedRevision": {
      "type": "integer",
      "description": "Latest revision expected by the caller. When supplied, stale restores fail with 409."
    }
  }
}

Schemas

Shared response/request object shapes referenced above (#/components/schemas/...):

Agent

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "displayName": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "modelPreference": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "deleted"
      ]
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "name",
    "displayName",
    "status"
  ]
}

BotConfig

{
  "type": "object",
  "properties": {
    "systemPrompt": {
      "type": "string"
    },
    "promptConfigVersion": {
      "type": "integer"
    },
    "promptSections": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "defaultModel": {
      "type": "string"
    },
    "maxTokens": {
      "type": "integer"
    }
  }
}

BotConfigUpdate

{
  "type": "object",
  "description": "Update the bot config. promptSections is the writable source of truth for prompt editing. The response still includes the composed systemPrompt for read-only inspection.",
  "properties": {
    "promptSections": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "defaultModel": {
      "type": "string"
    },
    "maxTokens": {
      "type": "integer",
      "minimum": 1024,
      "maximum": 32768
    }
  }
}

Error

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  },
  "required": [
    "error"
  ]
}

Flow

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "agentId": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "name"
  ]
}

Message

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "role": {
      "type": "string"
    },
    "content": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "role",
    "content"
  ]
}

NovaUser

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "role": {
      "type": "string"
    },
    "isActive": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "email",
    "role"
  ]
}

OverviewMetrics

{
  "type": "object",
  "properties": {
    "totalUsers": {
      "type": "integer"
    },
    "mrr": {
      "type": "number"
    },
    "churnRate": {
      "type": "number"
    }
  }
}

Report

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "title"
  ]
}

Skill

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "displayName": {
      "type": "string"
    },
    "instructions": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name"
  ]
}

SystemHealth

{
  "type": "object",
  "properties": {
    "overallStatus": {
      "type": "string"
    },
    "integrations": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  }
}

Thread

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived"
      ]
    },
    "source": {
      "type": "string"
    },
    "agentIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "title",
    "status"
  ]
}

UserWithBilling

{
  "type": "object",
  "properties": {
    "uid": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "PRO",
        "FREE",
        "LEGACY"
      ]
    }
  },
  "required": [
    "uid",
    "email",
    "status"
  ]
}

Version

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "entityType": {
      "type": "string",
      "enum": [
        "task-document",
        "agent-config",
        "agent",
        "flow",
        "skill",
        "project",
        "memory",
        "artifact",
        "database-record",
        "document"
      ]
    },
    "entityId": {
      "type": "string"
    },
    "revision": {
      "type": "integer"
    },
    "content": {
      "type": "string"
    },
    "contentHash": {
      "type": "string"
    },
    "kind": {
      "type": "string",
      "enum": [
        "snapshot",
        "restore",
        "delete"
      ]
    },
    "payload": {
      "type": "object",
      "additionalProperties": true
    },
    "author": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "id",
        "name"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "changeDescription": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "entityType",
    "entityId",
    "revision",
    "content",
    "contentHash",
    "kind",
    "author",
    "createdAt"
  ]
}

VersionDiff

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "text",
        "json"
      ]
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "op": {
            "type": "string",
            "enum": [
              "equal",
              "add",
              "remove"
            ]
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "op",
          "value"
        ]
      }
    },
    "changes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "before": {},
          "after": {}
        },
        "required": [
          "path"
        ]
      }
    }
  },
  "required": [
    "kind"
  ]
}

Browser automation & QA (Browserbase)

How any Nova agent drives a real remote browser via the browser_* tools — navigate, observe, act, extract, screenshot — plus the captcha + residential-proxy setup, live-view, session reuse across HITL pauses, and how to point this at QA/verification (nova-qa) not just directory submissions.

Agents

An agent is a Firestore-backed record that binds a persona, a model, a tool allowlist, and memory into something that can be invoked.

On this page

Base URLAuthenticationAuthAgentsPOST /api/v1/agentsDELETE /api/v1/agents/{id}GET /api/v1/agents/{id}PATCH /api/v1/agents/{id}SkillsDELETE /api/v1/agents/skills/{id}GET /api/v1/agents/skills/{id}PATCH /api/v1/agents/skills/{id}FlowsDELETE /api/v1/agents/flows/{id}GET /api/v1/agents/flows/{id}PATCH /api/v1/agents/flows/{id}POST /api/v1/agents/flows/{id}/triggerThreadsGET /api/v1/threadsDELETE /api/v1/threads/{id}GET /api/v1/threads/{id}PATCH /api/v1/threads/{id}DELETE /api/v1/threads/{id}/accessGET /api/v1/threads/{id}/accessPATCH /api/v1/threads/{id}/accessPOST /api/v1/threads/{id}/accessPOST /api/v1/threads/{id}/forkGET /api/v1/threads/{id}/messagesUsersGET /api/v1/usersGET /api/v1/users/{userId}GET /api/v1/users/{userId}/stripeGET /api/v1/users/{userId}/timelineGET /api/v1/users/{userId}/websitesNova UsersGET /api/v1/nova-users/{id}POST /api/v1/nova-users/{id}/deactivatePOST /api/v1/nova-users/{id}/reactivateAnalyticsReportsDELETE /api/v1/reports/{id}GET /api/v1/reports/{id}PATCH /api/v1/reports/{id}SettingsPUT /api/v1/bot-configSystemGET /api/v1/searchMCPPOST /api/v1/mcpCapsulesPOST /api/capsulesDELETE /api/capsules/{id}GET /api/capsules/{id}PATCH /api/capsules/{id}POST /api/capsules/{id}/rotate-tokenVersionsGET /api/v1/versions/{entityType}/{entityId}GET /api/v1/versions/{entityType}/{entityId}/{versionId}GET /api/v1/versions/{entityType}/{entityId}/{versionId}/diffPOST /api/v1/versions/{entityType}/{entityId}/{versionId}/restoreSchemasAgentBotConfigBotConfigUpdateErrorFlowMessageNovaUserOverviewMetricsReportSkillSystemHealthThreadUserWithBillingVersionVersionDiff