API Reference

Agents API

Complete reference for the Agents API endpoints

The Agents API provides access to AgentCore2 authority records. Agents represent people, collectives, and organizations involved in zine creation, publication, and distribution.

Endpoints

Method	Endpoint	Description
GET	/api/agents/	List all agents (paginated)
POST	/api/agents/	Create new agent
GET	/api/agents/{agent_id}/	Get specific agent
PUT	/api/agents/{agent_id}/	Replace agent (all fields)
PATCH	/api/agents/{agent_id}/	Update agent (partial)
DELETE	/api/agents/{agent_id}/	Delete agent

List Agents

Get paginated list of all agent records.

Request

GET /api/agents/

Authentication: Not required (public endpoint)

Query parameters:

page — Page number (default: 1)
page_size — Results per page (default: 25, max: 100)
search — Full-text search across display_name and biography
kind — Filter by agent kind
public — Filter by public status (true/false)
ordering — Sort field (prefix with - for descending)

Response

{
  "count": 523,
  "next": "http://localhost:8000/api/agents/?page=2",
  "previous": null,
  "results": [
    {
      "agent_id": "agent_judith_arcana",
      "kind": "Person",
      "display_name": "Judith Arcana",
      "public": true,
      "pronouns": ["she/her"],
      "biography": "Feminist writer and activist.",
      "website": "https://juditharcana.com",
      "created_at": "2024-02-25T10:30:00Z"
    }
  ]
}

Privacy filtering:

If public: false, sensitive fields (legal_name, email) are hidden
Private agents may not appear in public list views (depending on permissions)

Examples

Basic list:

curl http://localhost:8000/api/agents/

Search by name:

curl "http://localhost:8000/api/agents/?search=arcana"

Filter by kind:

curl "http://localhost:8000/api/agents/?kind=Person"

Only public agents:

curl "http://localhost:8000/api/agents/?public=true"

Sort by name:

curl "http://localhost:8000/api/agents/?ordering=display_name"

Get Agent

Retrieve a specific agent by external ID.

Request

GET /api/agents/{agent_id}/

Authentication: Not required (public endpoint)

URL parameters:

agent_id — Agent's external identifier (e.g., agent_judith_arcana)

Response

{
  "agent_id": "agent_judith_arcana",
  "kind": "Person",
  "display_name": "Judith Arcana",
  "public": true,
  "legal_name": "",
  "alternative_names": ["J. Arcana"],
  "sort_name": "Arcana, Judith",
  "pronouns": ["she/her"],
  "biography": "Feminist writer and activist, creator of reproductive rights zines.",
  "scope_note": ["Prefer citation as 'Judith Arcana'"],
  "roles": ["creator", "editor"],
  "orcid": "https://orcid.org/0000-0001-2345-6789",
  "wikidata": "Q12345678",
  "other_identifiers": ["VIAF:123456789"],
  "active_dates": ["1990-present"],
  "location": ["Seattle, WA"],
  "website": "https://juditharcana.com",
  "email": "",
  "social_media": ["https://twitter.com/juditharcana"],
  "created_at": "2024-02-25T10:30:00Z",
  "updated_at": "2024-02-25T10:30:00Z"
}

Privacy handling:

If public: false, sensitive fields are omitted:
- legal_name (not shown)
- email (not shown)
- phone (not shown)

Examples

Get agent:

curl http://localhost:8000/api/agents/agent_judith_arcana/

Get as JSON-LD:

curl -H "Accept: application/ld+json" \
  http://localhost:8000/api/agents/agent_judith_arcana/

Create Agent

Create a new agent record.

Request

POST /api/agents/
Content-Type: application/json
Authorization: Token YOUR_TOKEN

Authentication: Required

Required Fields

Field	Type	Description	Example
agent_id	string	Unique external identifier	"agent_judith_arcana"
kind	string	Agent type (see vocabulary)	"Person"
display_name	string	Public display name	"Judith Arcana"
public	boolean	Public visibility flag	true

Optional Fields

Field	Type	Description	Example
legal_name	string	Legal/full name (may be private)	"Judith Arcana"
alternative_names	arraystring	Pseudonyms, former names	["J. Arcana"]
sort_name	string	Name for alphabetical sorting	"Arcana, Judith"
pronouns	arraystring	Preferred pronouns	["she/her"]
biography	string	Biographical statement	"Feminist writer..."
scope_note	arraystring	Usage notes	["Prefer 'Judith Arcana'"]
roles	arraystring	Common roles (vocabulary codes)	["creator", "editor"]
orcid	string (URL)	ORCID identifier	"https://orcid.org/..."
wikidata	string	Wikidata Q-ID	"Q12345678"
other_identifiers	arraystring	VIAF, ISNI, local IDs	["VIAF:123456"]
active_dates	arraystring	Date ranges when active	["1990-present"]
location	arraystring	Geographic locations	["Seattle, WA"]
website	string (URL)	Personal/org website	"https://example.com"
email	string (email)	Contact email (private)	"[email protected]"
social_media	arraystring	Social media URLs	["https://twitter.com/..."]

Request Example

curl -X POST http://localhost:8000/api/agents/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_judith_arcana",
    "kind": "Person",
    "display_name": "Judith Arcana",
    "public": true,
    "pronouns": ["she/her"],
    "biography": "Feminist writer and activist.",
    "website": "https://juditharcana.com",
    "roles": ["creator", "editor"]
  }'

Response (201 Created)

Returns the full agent object:

{
  "agent_id": "agent_judith_arcana",
  "kind": "Person",
  "display_name": "Judith Arcana",
  "public": true,
  "pronouns": ["she/her"],
  "biography": "Feminist writer and activist.",
  "website": "https://juditharcana.com",
  "roles": ["creator", "editor"],
  "created_at": "2024-02-25T10:30:00Z",
  "updated_at": "2024-02-25T10:30:00Z"
}

Update Agent

Update an existing agent record.

PATCH (Partial Update)

Update only specific fields.

PATCH /api/agents/{agent_id}/
Content-Type: application/json
Authorization: Token YOUR_TOKEN

Request:

curl -X PATCH http://localhost:8000/api/agents/agent_judith_arcana/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "biography": "Updated biography with more detail.",
    "website": "https://newsite.com"
  }'

PUT (Full Replacement)

Replace the entire agent record.

PUT /api/agents/{agent_id}/
Content-Type: application/json
Authorization: Token YOUR_TOKEN

All required fields must be provided.

Response (200 OK)

Returns the updated full agent object.

Delete Agent

Delete an agent record.

Request

DELETE /api/agents/{agent_id}/
Authorization: Token YOUR_TOKEN

Example:

curl -X DELETE http://localhost:8000/api/agents/agent_judith_arcana/ \
  -H "Authorization: Token YOUR_TOKEN"

Response (204 No Content)

Warning: Deleting an agent will NOT delete zines that reference it, but will break the relationship (zine.creator will contain an invalid ID).

Best practice: Don't delete agents that are referenced by zines. Instead, mark as public: false to hide.

Field Details

agent_id

Type: string (max 255 characters) Required: Yes Unique: Yes

External unique identifier for the agent.

Naming convention: agent_{name_slug}

Examples:

agent_judith_arcana
agent_kathleen_hanna
agent_mimi_nguyen
agent_zinester_collective
agent_microcosm_publishing
agent_anonymous_zinester_seattle

kind

Type: string (max 50 characters) Required: Yes Repeatable: No

Agent type from the Agent Kinds vocabulary.

Valid values:

Person — Individual person
Collective — Informal group
Organization — Formal organization

See vocabulary: /api/vocabularies/agent-kinds/

display_name

Type: string (max 500 characters) Required: Yes Repeatable: No

Public name for display (may be pseudonym).

Examples:

"Judith Arcana"
"Zinester Collective"
"Microcosm Publishing"
"Anonymous"

public

Type: boolean Required: Yes Repeatable: No Default: true

Whether agent details may be shown publicly.

If public: false:

legal_name is hidden
email is hidden
phone is hidden
Agent may not appear in public listings

Use cases for private agents:

Anonymous contributors
Agents who want limited public visibility
Internal-only records

legal_name

Type: string (max 500 characters) Required: No Repeatable: No Privacy: Hidden if public: false

Legal or full name (may be private).

Examples:

"Judith Arcana"
"Kathleen Hannah"
""

alternative_names

Type: array of strings (max 500 characters each) Required: No Repeatable: Yes

Pseudonyms, former names, or variant names.

Examples:

["J. Arcana", "Judy Arcana"]
["Kathleen Hanna", "Julie Ruin"]
[]

sort_name

Type: string (max 500 characters) Required: No Repeatable: No

Name formatted for alphabetical sorting.

Format: Last, First or Organization Name

Examples:

"Arcana, Judith"
"Hanna, Kathleen"
"Microcosm Publishing"

pronouns

Type: array of strings (max 50 characters each) Required: No Repeatable: Yes

Preferred pronouns.

Examples:

["she/her"]
["he/him"]
["they/them"]
["she/they"]
["any pronouns"]
[]

biography

Type: string (text field, no max length) Required: No Repeatable: No

Biographical statement or description.

Examples:

"Feminist writer and activist, creator of reproductive rights zines."
"Punk zinester based in Seattle since 1995."
"Anarchist publishing collective founded in Portland, OR."

scope_note

Type: array of strings (text fields) Required: No Repeatable: Yes

Usage notes or preferred citation.

Examples:

["Prefer citation as 'Judith Arcana'"]
["Use pseudonym 'J. A.' for early works"]
[]

roles

Type: array of strings (role codes from vocabulary) Required: No Repeatable: Yes

Common roles this agent performs.

Valid values:

creator
editor
illustrator
publisher
distributor
... (see vocabulary)

See vocabulary: /api/vocabularies/agent-roles/

Examples:

["creator", "editor"]
["publisher", "distributor"]
["illustrator"]
[]

orcid

Type: string (URL format) Required: No Repeatable: No

ORCID identifier URL.

Format: https://orcid.org/XXXX-XXXX-XXXX-XXXX

Examples:

"https://orcid.org/0000-0001-2345-6789"
""

wikidata

Type: string (max 50 characters) Required: No Repeatable: No

Wikidata Q-ID.

Format: QXXXXXXX

Examples:

"Q12345678"
""

other_identifiers

Type: array of strings (max 255 characters each) Required: No Repeatable: Yes

VIAF, ISNI, local authority IDs, etc.

Examples:

["VIAF:123456789", "ISNI:0000000121234567"]
["Local:AUTH-001"]
[]

active_dates

Type: array of strings (max 100 characters each) Required: No Repeatable: Yes

Date ranges when agent was active.

Examples:

["1990-present"]
["1995-2005"]
["c. 2000-2010", "2015-present"]
[]

location

Type: array of strings (max 255 characters each) Required: No Repeatable: Yes

Geographic locations associated with agent.

Examples:

["Seattle, WA"]
["Portland, OR", "Brooklyn, NY"]
["Online"]
[]

website

Type: string (URL format, max 255 characters) Required: No Repeatable: No

Personal or organizational website.

Examples:

"https://juditharcana.com"
"https://microcosmpublishing.com"
""

email

Type: string (email format, max 254 characters) Required: No Repeatable: No Privacy: Hidden if public: false

Contact email address.

Examples:

"[email protected]"
""

Not exposed by default — even for public agents, email may be internal-only.

social_media

Type: array of strings (URL format) Required: No Repeatable: Yes

Social media profile URLs.

Examples:

["https://twitter.com/juditharcana", "https://instagram.com/juditharcana"]
["https://mastodon.social/@username"]
[]

Privacy Examples

Public Agent (Full Disclosure)

Request:

{
  "agent_id": "agent_public_person",
  "kind": "Person",
  "display_name": "Public Person",
  "public": true,
  "legal_name": "Public Full Name",
  "email": "[email protected]"
}

Response (GET):

{
  "agent_id": "agent_public_person",
  "kind": "Person",
  "display_name": "Public Person",
  "public": true,
  "legal_name": "Public Full Name",
  "email": "[email protected]"
}

All fields visible.

Private Agent (Limited Disclosure)

Request:

{
  "agent_id": "agent_private_person",
  "kind": "Person",
  "display_name": "Anonymous Zinester",
  "public": false,
  "legal_name": "Private Full Name",
  "email": "[email protected]"
}

Response (GET):

{
  "agent_id": "agent_private_person",
  "kind": "Person",
  "display_name": "Anonymous Zinester",
  "public": false
  // legal_name NOT included
  // email NOT included
}

Sensitive fields hidden.

Agent Types

Person

Individual creator, contributor, or publisher.

Example:

{
  "agent_id": "agent_kathleen_hanna",
  "kind": "Person",
  "display_name": "Kathleen Hanna",
  "public": true,
  "pronouns": ["she/her"],
  "biography": "Musician and zinester, creator of Bikini Kill zine."
}

Collective

Informal group or collaborative.

Example:

{
  "agent_id": "agent_zinester_collective",
  "kind": "Collective",
  "display_name": "Seattle Zinester Collective",
  "public": true,
  "biography": "Collaborative zine-making collective founded in 2010."
}

Organization

Formal organization, publisher, or distro.

Example:

{
  "agent_id": "agent_microcosm_publishing",
  "kind": "Organization",
  "display_name": "Microcosm Publishing",
  "public": true,
  "website": "https://microcosmpublishing.com",
  "location": ["Portland, OR"]
}

Validation Errors

Missing Required Field

Response (400 Bad Request):

{
  "kind": ["This field is required."],
  "display_name": ["This field is required."],
  "public": ["This field is required."]
}

Invalid Kind

Request:

{
  "kind": "InvalidKind"
}

Response (400 Bad Request):

{
  "kind": ["Invalid kind: InvalidKind. Must be one of ['Person', 'Collective', 'Organization']"]
}

Duplicate agent_id

Response (400 Bad Request):

{
  "agent_id": ["Agent with this agent_id already exists."]
}

Code Examples

Python

import requests

API_BASE = "http://localhost:8000/api"
TOKEN = "YOUR_TOKEN"
headers = {
    "Authorization": f"Token {TOKEN}",
    "Content-Type": "application/json"
}

# Create agent
agent_data = {
    "agent_id": "agent_jane_doe",
    "kind": "Person",
    "display_name": "Jane Doe",
    "public": True,
    "pronouns": ["she/her"],
    "biography": "Zinester based in Brooklyn."
}

response = requests.post(
    f"{API_BASE}/agents/",
    headers=headers,
    json=agent_data
)

print(f"Created: {response.json()['display_name']}")

# Get agent
agent = requests.get(f"{API_BASE}/agents/agent_jane_doe/").json()
print(f"Biography: {agent['biography']}")

# Update agent
requests.patch(
    f"{API_BASE}/agents/agent_jane_doe/",
    headers=headers,
    json={"website": "https://janedoe.com"}
)

JavaScript

const API_BASE = "http://localhost:8000/api";
const TOKEN = "YOUR_TOKEN";

// Create agent
const agentData = {
  agent_id: "agent_jane_doe",
  kind: "Person",
  display_name: "Jane Doe",
  public: true,
  pronouns: ["she/her"]
};

const response = await fetch(`${API_BASE}/agents/`, {
  method: "POST",
  headers: {
    "Authorization": `Token ${TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(agentData)
});

const agent = await response.json();
console.log(`Created: ${agent.display_name}`);

Next Steps

Zines API — Zines endpoints reference
Holdings API — Holdings endpoints reference
Filtering — Advanced filtering and search

Edit this pageorReport an issue

Zines API

Complete reference for the Zines API endpoints

Holdings API

Complete reference for the Holdings API endpoints