API Users
Pull your team's Agent Contexts into any product surface.
Use ProxVanta as the prompt source of truth for assistants, internal tools, jobs, and workflow automation.
Why developers care
No prompt strings in code
Fetch one shared Agent Context instead of hardcoding prompts into product routes, workers, and tools.
One source of truth
Use the same context across assistants, internal tools, jobs, and product workflows.
Update without deploys
Change the Agent Context in ProxVanta and let clients pick up the latest version.
Public to private path
Start from public contexts, then use private org-specific versions through the same API shape.
Documentation
List Agent Contexts
Use limit and cursor for simple pagination. Start here when you want to see what your team has available.
# default fields to include: context
curl -sS \
-H "Authorization: Bearer $PROXVANTA_API_KEY" \
"https://api.proxvanta.com/v1/agent-contexts?limit=10"
# specific fields to include (default value: 'context')
curl -sS \
-H "Authorization: Bearer $PROXVANTA_API_KEY" \
"https://api.proxvanta.com/v1/agent-contexts?limit=10&include=context,structured"from urllib.request import Request, urlopen
request = Request(
"https://api.proxvanta.com/v1/agent-contexts?limit=10",
headers={"Authorization": "Bearer " + PROXVANTA_API_KEY},
)
with urlopen(request) as response:
print(response.read().decode("utf-8"))const response = await fetch("https://api.proxvanta.com/v1/agent-contexts?limit=10", {
headers: {
Authorization: `Bearer ${process.env.PROXVANTA_API_KEY}`,
},
});
const payload = await response.json();
console.log(payload.data[0]?.context);// Default fields to include: context.
const defaultResponse = await fetch("https://api.proxvanta.com/v1/agent-contexts?limit=10", {
headers: {
Authorization: `Bearer ${process.env.PROXVANTA_API_KEY ?? ""}`,
},
});
const defaultPayload = (await defaultResponse.json()) as ListAgentContextsResponse;
console.log(defaultPayload.data[0]?.context);
// Specific fields to include.
const structuredResponse = await fetch(
"https://api.proxvanta.com/v1/agent-contexts?limit=10&include=context,structured",
{
headers: {
Authorization: `Bearer ${process.env.PROXVANTA_API_KEY ?? ""}`,
},
},
);
const structuredPayload = (await structuredResponse.json()) as ListAgentContextsResponse;
console.log(structuredPayload.data[0]?.context);
console.log(structuredPayload.data[0]?.structuredData.name);var request = java.net.http.HttpRequest.newBuilder()
.uri(java.net.URI.create("https://api.proxvanta.com/v1/agent-contexts?limit=10"))
.header("Authorization", "Bearer " + System.getenv("PROXVANTA_API_KEY"))
.build();
var client = java.net.http.HttpClient.newHttpClient();
var response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());req, err := http.NewRequest(
http.MethodGet,
"https://api.proxvanta.com/v1/agent-contexts?limit=10",
nil,
)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("PROXVANTA_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(body))require "net/http"
require "uri"
uri = URI("https://api.proxvanta.com/v1/agent-contexts?limit=10")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("PROXVANTA_API_KEY")}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
http.request(request)
end
puts response.bodyGet One Agent Context
Fetch one Agent Context directly. Use the Agent Context template key as the id, for example `designer`.
# current version
curl -sS \
-H "Authorization: Bearer $PROXVANTA_API_KEY" \
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}"
# specific historical version
curl -sS \
-H "Authorization: Bearer $PROXVANTA_API_KEY" \
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}?version=2"from urllib.request import Request, urlopen
request = Request(
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}",
headers={"Authorization": "Bearer " + PROXVANTA_API_KEY},
)
with urlopen(request) as response:
print(response.read().decode("utf-8"))const response = await fetch("https://api.proxvanta.com/v1/agent-contexts/{agentContextId}", {
headers: {
Authorization: `Bearer ${process.env.PROXVANTA_API_KEY}`,
},
});
const payload = await response.json();
console.log(payload.structuredData);// Current version.
const response = await fetch(
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}",
{
headers: {
Authorization: `Bearer ${process.env.PROXVANTA_API_KEY ?? ""}`,
},
},
);
// Specific historical version.
const versionedResponse = await fetch(
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}?version=2",
{
headers: {
Authorization: `Bearer ${process.env.PROXVANTA_API_KEY ?? ""}`,
},
},
);
const payload = (await response.json()) as GetAgentContextResponse;
const versionedPayload = (await versionedResponse.json()) as GetAgentContextResponse;
console.log(payload.structuredData.privateInstructions);
console.log(versionedPayload.structuredData.version);var request = java.net.http.HttpRequest.newBuilder()
.uri(java.net.URI.create("https://api.proxvanta.com/v1/agent-contexts/{agentContextId}"))
.header("Authorization", "Bearer " + System.getenv("PROXVANTA_API_KEY"))
.build();
var client = java.net.http.HttpClient.newHttpClient();
var response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());req, err := http.NewRequest(
http.MethodGet,
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}",
nil,
)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("PROXVANTA_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(body))require "net/http"
require "uri"
uri = URI("https://api.proxvanta.com/v1/agent-contexts/{agentContextId}")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("PROXVANTA_API_KEY")}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
http.request(request)
end
puts response.bodyGet One Agent Context Version
Use this when you want to pin your code to a specific historical version instead of the current one.
# version query param
curl -sS \
-H "Authorization: Bearer $PROXVANTA_API_KEY" \
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}?version=2"
# version suffix
curl -sS \
-H "Authorization: Bearer $PROXVANTA_API_KEY" \
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}@2"from urllib.request import Request, urlopen
request = Request(
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}?version=2",
headers={"Authorization": "Bearer " + PROXVANTA_API_KEY},
)
with urlopen(request) as response:
print(response.read().decode("utf-8"))const response = await fetch("https://api.proxvanta.com/v1/agent-contexts/{agentContextId}?version=2", {
headers: {
Authorization: `Bearer ${process.env.PROXVANTA_API_KEY}`,
},
});
const payload = await response.json();
console.log(payload.structuredData);const response = await fetch(
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}?version=2",
{
headers: {
Authorization: `Bearer ${process.env.PROXVANTA_API_KEY ?? ""}`,
},
},
);
const payload = (await response.json()) as GetAgentContextResponse;
console.log(payload.structuredData.privateInstructions);var request = java.net.http.HttpRequest.newBuilder()
.uri(java.net.URI.create("https://api.proxvanta.com/v1/agent-contexts/{agentContextId}?version=2"))
.header("Authorization", "Bearer " + System.getenv("PROXVANTA_API_KEY"))
.build();
var client = java.net.http.HttpClient.newHttpClient();
var response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());req, err := http.NewRequest(
http.MethodGet,
"https://api.proxvanta.com/v1/agent-contexts/{agentContextId}?version=2",
nil,
)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("PROXVANTA_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(body))require "net/http"
require "uri"
uri = URI("https://api.proxvanta.com/v1/agent-contexts/{agentContextId}?version=2")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("PROXVANTA_API_KEY")}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
http.request(request)
end
puts response.bodyRequest and Response Types
Use these language definitions as the query parameter and response shape reference. These GET endpoints do not accept JSON request bodies.
Did you know?
- `context` is the compiled reusable Agent Context prompt.
- `structuredData` is the full Agent Context object for UI, debugging, analytics, or custom client behavior.
type AgentContextStructuredData = {
id: string;
createdAt: string;
updatedAt?: string;
createdByUserId: string;
role?: string;
version?: number;
name: string;
slug: string;
shortName: string;
teammateLabel: string;
description: string;
focus: string[];
whenToUse: string[];
suggestedPrompts: string[];
routingHints: string[];
personality: string;
operatingStyle: string;
scope?: string;
decisionRules?: string[];
instructions: string;
privateInstructions?: string;
outputFormat?: "markdown" | "structured" | "conversational";
structuredOutputExample?: string;
worksWellWith?: string[];
guardrails?: string[];
longPromptThreshold?: 1500 | 2500 | 4000;
tools?: string[];
skills?: string[];
categories?: string[];
tags?: string[];
visibility?: "private" | "team" | "public";
publishedHandle?: string;
sourceHandle?: string;
sourceOrganizationSlug?: string;
sourceIsPublished?: boolean;
syncEnabled?: boolean;
usageCount?: number;
lastUsedAt?: string;
promptTokenEstimateTotal?: number;
lastPromptTokenEstimate?: number;
enabled: boolean;
};
type AgentContextResponse = {
context: string;
structuredData: AgentContextStructuredData;
usage?: {
usageEventId: string;
source: "api";
operation: "get_agent_context";
promptTokenEstimate?: number;
};
};
type ListAgentContextsResponse = {
data: AgentContextResponse[];
nextCursor?: string;
totalCount: number;
};
type ListAgentContextsQueryParams = {
cursor?: string;
limit?: number;
include?: "context" | "structured" | "context,structured";
};
type GetAgentContextPathParams = {
agentContextId: string;
};
type GetAgentContextQueryParams = {
version?: number;
};
type GetAgentContextResponse = AgentContextResponse;from typing import Literal, NotRequired, TypedDict
AgentContextOutputFormat = Literal["markdown", "structured", "conversational"]
class AgentContextStructuredData(TypedDict, total=False):
id: str
createdAt: str
updatedAt: str
createdByUserId: str
role: str
version: int
name: str
slug: str
shortName: str
teammateLabel: str
description: str
focus: list[str]
whenToUse: list[str]
suggestedPrompts: list[str]
routingHints: list[str]
personality: str
operatingStyle: str
scope: str
decisionRules: list[str]
instructions: str
privateInstructions: str
outputFormat: AgentContextOutputFormat
structuredOutputExample: str
worksWellWith: list[str]
guardrails: list[str]
longPromptThreshold: int
tools: list[str]
skills: list[str]
categories: list[str]
tags: list[str]
visibility: Literal["private", "team", "public"]
publishedHandle: str
enabled: bool
class AgentContextResponse(TypedDict):
context: str
structuredData: AgentContextStructuredData
usage: NotRequired[dict[str, str | int]]
class ListAgentContextsResponse(TypedDict, total=False):
data: list[AgentContextResponse]
nextCursor: str
totalCount: int
class ListAgentContextsQueryParams(TypedDict, total=False):
cursor: str
limit: int
include: Literal["context", "structured", "context,structured"]
class GetAgentContextPathParams(TypedDict):
agentContextId: str
class GetAgentContextQueryParams(TypedDict, total=False):
version: int
class GetAgentContextResponse(AgentContextResponse):
pass/**
* @typedef {Object} AgentContextStructuredData
* @property {string} id
* @property {string} createdAt
* @property {string=} updatedAt
* @property {string} createdByUserId
* @property {string=} role
* @property {number=} version
* @property {string} name
* @property {string} slug
* @property {string} shortName
* @property {string} teammateLabel
* @property {string} description
* @property {string[]} focus
* @property {string[]} whenToUse
* @property {string[]} suggestedPrompts
* @property {string[]} routingHints
* @property {string} personality
* @property {string} operatingStyle
* @property {string=} scope
* @property {string[]=} decisionRules
* @property {string} instructions
* @property {string=} privateInstructions
* @property {"markdown" | "structured" | "conversational"=} outputFormat
* @property {string[]=} worksWellWith
* @property {string[]=} guardrails
* @property {string[]=} tools
* @property {string[]=} skills
* @property {boolean} enabled
*
* @typedef {Object} AgentContextResponse
* @property {string} context
* @property {AgentContextStructuredData} structuredData
* @property {{ usageEventId: string, source: "api", operation: "get_agent_context", promptTokenEstimate?: number }=} usage
*/public record AgentContextStructuredData(
String id,
String createdAt,
String updatedAt,
String createdByUserId,
String role,
Integer version,
String name,
String slug,
String shortName,
String teammateLabel,
String description,
List<String> focus,
List<String> whenToUse,
List<String> suggestedPrompts,
List<String> routingHints,
String personality,
String operatingStyle,
String scope,
List<String> decisionRules,
String instructions,
String privateInstructions,
String outputFormat,
List<String> worksWellWith,
List<String> guardrails,
List<String> tools,
List<String> skills,
boolean enabled
) {}
public record AgentContextResponse(
String context,
AgentContextStructuredData structuredData,
Map<String, Object> usage
) {}type AgentContextStructuredData struct {
ID string `json:"id"`
CreatedAt string `json:"createdAt"`
UpdatedAt *string `json:"updatedAt,omitempty"`
CreatedByUserID string `json:"createdByUserId"`
Role *string `json:"role,omitempty"`
Version *int `json:"version,omitempty"`
Name string `json:"name"`
Slug string `json:"slug"`
ShortName string `json:"shortName"`
TeammateLabel string `json:"teammateLabel"`
Description string `json:"description"`
Focus []string `json:"focus"`
WhenToUse []string `json:"whenToUse"`
SuggestedPrompts []string `json:"suggestedPrompts"`
RoutingHints []string `json:"routingHints"`
Personality string `json:"personality"`
OperatingStyle string `json:"operatingStyle"`
Instructions string `json:"instructions"`
Enabled bool `json:"enabled"`
}
type AgentContextResponse struct {
Context string `json:"context"`
StructuredData AgentContextStructuredData `json:"structuredData"`
Usage map[string]interface{} `json:"usage,omitempty"`
}module ProxVanta
class AgentContextStructuredData < T::Struct
const :id, String
const :created_at, String
prop :updated_at, T.nilable(String)
const :created_by_user_id, String
prop :role, T.nilable(String)
prop :version, T.nilable(Integer)
const :name, String
const :slug, String
const :short_name, String
const :teammate_label, String
const :description, String
const :focus, T::Array[String]
const :when_to_use, T::Array[String]
const :suggested_prompts, T::Array[String]
const :routing_hints, T::Array[String]
const :personality, String
const :operating_style, String
const :instructions, String
const :enabled, T::Boolean
end
class AgentContextResponse < T::Struct
const :context, String
const :structured_data, AgentContextStructuredData
prop :usage, T.nilable(T::Hash[String, T.untyped])
end
endExample Responses
Use these JSON payloads as concrete examples of the API responses.
List Agent Contexts
{
"data": [
{
"context": "## Role\n\nYou are a designer.\n\nReviews flows, UX details, and design direction."
}
],
"nextCursor": "10",
"totalCount": 24
}Get Agent Context
{
"context": "## Role\n\nYou are a designer.\n\nReviews flows, UX details, and design direction.\n\n## Scope\n\nFocus on UX quality, product flows, missing states, and interaction gaps.",
"structuredData": {
"id": "organization-agent-context#org_123#designer",
"createdByUserId": "user_123",
"role": "designer",
"version": 3,
"name": "Designer",
"slug": "designer",
"shortName": "designer",
"teammateLabel": "designer",
"description": "Reviews flows, UX details, and design direction.",
"focus": [
"UX review",
"interface polish"
],
"whenToUse": [
"When you want a fast critique of a flow or screen",
"When you need design tradeoffs explained clearly"
],
"suggestedPrompts": [
"Review this onboarding flow and call out friction."
],
"routingHints": [
"design",
"ux",
"flow",
"wireframe"
],
"personality": "Direct, sharp, and product-minded.",
"operatingStyle": "Give feedback in priority order with concrete fixes.",
"scope": "Focus on UX quality, product flows, missing states, and interaction gaps.",
"decisionRules": [
"Start with the most important friction or confusion.",
"Call out missing states before visual polish.",
"Be specific about the screen, component, or step."
],
"instructions": "Act as the organization's design collaborator.",
"privateInstructions": "Prefer the company's current design system.",
"outputFormat": "markdown",
"worksWellWith": [
"figma",
"codex"
],
"guardrails": [
"warn-before-long-prompt"
],
"longPromptThreshold": 2500,
"tools": [
"figma:read",
"web:search"
],
"skills": [
"ux-review",
"documentation"
],
"categories": [
"design",
"product"
],
"tags": [
"onboarding",
"ux"
],
"publishedHandle": "acme/designer",
"usageCount": 14,
"lastUsedAt": "2026-04-01T02:15:00.000Z",
"promptTokenEstimateTotal": 8400,
"lastPromptTokenEstimate": 620,
"enabled": true
},
"usage": {
"usageEventId": "organization-agent-context-usage#org_123#organization-agent-context#org_123#designer#api#get_agent_context#2026-04-01T02:15:00.000Z#ab12cd34",
"source": "api",
"operation": "get_agent_context",
"promptTokenEstimate": 620
}
}Error shape
{
"error": "entitlement_feature_unavailable(feature:api_access,plan:free,required:pro)",
"feature": "api_access",
"requiredPlan": "pro",
"upgradePath": "/dashboard/organization/billing"
}