API Reference

Repositories API

Complete reference for the Repositories API endpoints

The Repositories API provides access to RepoCore2 institutional records. Repositories represent libraries, archives, distros, and collections that hold zines.

Endpoints

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

List Repositories

Get paginated list of all repositories.

Request

GET /api/repositories/

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 name and description
repository_kind — Filter by repository type
country — Filter by country code (ISO 3166-1 alpha-2)
status — Filter by status (active/inactive/defunct)
ordering — Sort field

Response

{
  "count": 523,
  "next": "http://localhost:8000/api/repositories/?page=2",
  "previous": null,
  "results": [
    {
      "repo_id": "repo_barnard_zine_library",
      "repository_name": "Barnard Zine Library",
      "repository_kind": "academic-library",
      "country": "US",
      "city": "New York",
      "region": "NY",
      "website": "https://zines.barnard.edu",
      "status": "active",
      "created_at": "2024-02-20T10:00:00Z"
    }
  ]
}

Examples

Basic list:

curl http://localhost:8000/api/repositories/

Search by name:

curl "http://localhost:8000/api/repositories/?search=barnard"

Filter by kind:

curl "http://localhost:8000/api/repositories/?repository_kind=academic-library"

Filter by country:

curl "http://localhost:8000/api/repositories/?country=US"

Only active repositories:

curl "http://localhost:8000/api/repositories/?status=active"

Sort alphabetically:

curl "http://localhost:8000/api/repositories/?ordering=repository_name"

Get Repository

Retrieve a specific repository by external ID.

Request

GET /api/repositories/{repo_id}/

Authentication: Not required (public endpoint)

URL parameters:

repo_id — Repository's external identifier

Response

{
  "repo_id": "repo_barnard_zine_library",
  "repository_name": "Barnard Zine Library",
  "repository_kind": "academic-library",
  "country": "US",
  "alternative_names": ["Barnard Zine Collection"],
  "description": "Barnard College's zine library, one of the largest academic zine collections in the US.",
  "scope_note": "Focuses on feminist, queer, and social justice zines.",
  "marc_org_code": "NNC-Z",
  "isil": "US-NNC-Z",
  "ror": "",
  "city": "New York",
  "region": "NY",
  "postal_code": "10027",
  "website": "https://zines.barnard.edu",
  "email": "[email protected]",
  "phone": "+1-212-854-2233",
  "social_media": [
    "https://twitter.com/barnardzines",
    "https://instagram.com/barnardzines"
  ],
  "holdings_count": 3421,
  "established": "2003",
  "status": "active",
  "created_at": "2024-02-20T10:00:00Z",
  "updated_at": "2024-02-25T14:00:00Z"
}

Examples

Get repository:

curl http://localhost:8000/api/repositories/repo_barnard_zine_library/

Get as JSON-LD:

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

Create Repository

Create a new repository record.

Request

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

Authentication: Required

Required Fields

Field	Type	Description	Example
repo_id	string	Unique external identifier	"repo_barnard_zine_library"
repository_name	string	Official repository name	"Barnard Zine Library"
repository_kind	string	Repository type (vocabulary code)	"academic-library"
country	string	ISO 3166-1 alpha-2 code	"US"

Optional Fields

Field	Type	Description	Example
alternative_names	arraystring	Former names, abbreviations	["Barnard Zine Collection"]
description	string	Repository description	"Academic zine library..."
scope_note	string	Collection scope	"Focus on feminist zines"
marc_org_code	string	MARC Organization Code	"NNC-Z"
isil	string	ISO 15511 ISIL identifier	"US-NNC-Z"
ror	string (URL)	ROR ID	"https://ror.org/..."
city	string	City	"New York"
region	string	State/province	"NY"
postal_code	string	Postal/ZIP code	"10027"
website	string (URL)	Repository website	"https://zines.barnard.edu"
email	string (email)	Contact email	"[email protected]"
phone	string	Phone number	"+1-212-854-2233"
social_media	arraystring	Social media URLs	["https://twitter.com/..."]
holdings_count	integer	Approximate holdings count	3421
established	string	Year established	"2003"
status	string	Status: active/inactive/defunct	"active"

Request Example

curl -X POST http://localhost:8000/api/repositories/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": "repo_barnard_zine_library",
    "repository_name": "Barnard Zine Library",
    "repository_kind": "academic-library",
    "country": "US",
    "city": "New York",
    "region": "NY",
    "website": "https://zines.barnard.edu",
    "email": "[email protected]",
    "established": "2003",
    "status": "active",
    "description": "Barnard Colleges zine library, one of the largest academic zine collections.",
    "scope_note": "Focuses on feminist, queer, and social justice zines."
  }'

Response (201 Created)

Returns the full repository object:

{
  "repo_id": "repo_barnard_zine_library",
  "repository_name": "Barnard Zine Library",
  "repository_kind": "academic-library",
  "country": "US",
  "city": "New York",
  "region": "NY",
  "website": "https://zines.barnard.edu",
  "email": "[email protected]",
  "status": "active",
  "created_at": "2024-02-25T14:00:00Z",
  "updated_at": "2024-02-25T14:00:00Z"
}

Update Repository

Update an existing repository record.

PATCH (Partial Update)

PATCH /api/repositories/{repo_id}/
Content-Type: application/json
Authorization: Token YOUR_TOKEN

Request:

curl -X PATCH http://localhost:8000/api/repositories/repo_barnard_zine_library/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description with more detail.",
    "holdings_count": 3500
  }'

PUT (Full Replacement)

PUT /api/repositories/{repo_id}/
Content-Type: application/json
Authorization: Token YOUR_TOKEN

All required fields must be provided.

Response (200 OK)

Returns the updated full repository object.

Delete Repository

Delete a repository record.

Request

DELETE /api/repositories/{repo_id}/
Authorization: Token YOUR_TOKEN

Example:

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

Response (204 No Content)

Cascade behavior:

All holdings referencing this repository are also deleted
Zines are NOT deleted (only the relationship is removed)

Field Details

repo_id

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

External unique identifier for the repository.

Naming convention: repo_{institution_slug}

Examples:

repo_barnard_zine_library
repo_qzap
repo_abc_no_rio
repo_my_personal_collection

repository_name

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

Official name of the repository.

Examples:

"Barnard Zine Library"
"Queer Zine Archive Project"
"ABC No Rio Zine Library"
"My Personal Zine Collection"

repository_kind

Type: string (max 100 characters, vocabulary code) Required: Yes Repeatable: No

Repository type from the Repository Kinds vocabulary.

Valid values:

academic-library
public-library
special-library
archive
community-archive
distro
personal-collection
museum
other

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

Examples:

"academic-library"
"distro"
"personal-collection"

country

Type: string (2 characters, ISO 3166-1 alpha-2) Required: Yes Repeatable: No

Country code.

Format: 2-letter ISO 3166-1 alpha-2 code

Examples:

"US"
"CA"
"GB"
"AU"

See list: /api/geography/countries/

alternative_names

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

Former names, abbreviations, or variants.

Examples:

["Barnard Zine Collection"]
["QZAP"]
["ABC"]
[]

description

Type: string (text field) Required: No Repeatable: No

Description of the repository.

Examples:

"Barnard College's zine library, one of the largest academic zine collections in the United States."
"Community-run zine distro focused on queer and trans voices."

scope_note

Type: string (text field) Required: No Repeatable: No

Collection scope and specializations.

Examples:

"Focuses on feminist, queer, and social justice zines."
"Primarily punk and DIY music zines from the 1990s."
"Comprehensive collection of Pacific Northwest zines."

marc_org_code

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

MARC Organization Code assigned by Library of Congress.

Examples:

"NNC-Z"
"MH-Z"
""

isil

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

ISO 15511 International Standard Identifier for Libraries and Related Organizations.

Format: {country code}-{organization code}

Examples:

"US-NNC-Z"
"CA-OTUTF"
""

ror

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

Research Organization Registry (ROR) identifier URL.

Format: https://ror.org/{id}

Examples:

"https://ror.org/02w0r2764"
""

city

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

City where repository is located.

Examples:

"New York"
"Portland"
"Online"

region

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

State, province, or region.

Examples:

"NY"
"OR"
"British Columbia"

postal_code

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

Postal or ZIP code.

Examples:

"10027"
"97202"
"M5S 1A1"

website

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

Repository website.

Examples:

"https://zines.barnard.edu"
"https://www.qzap.org"
""

email

Type: string (email format, max 254 characters) Required: No Repeatable: No

Contact email address.

Examples:

"[email protected]"
"[email protected]"
""

phone

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

Phone number (any format).

Examples:

"+1-212-854-2233"
"(503) 555-1234"
""

social_media

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

Social media profile URLs.

Examples:

["https://twitter.com/barnardzines", "https://instagram.com/barnardzines"]
["https://mastodon.social/@zines"]
[]

holdings_count

Type: integer Required: No Repeatable: No

Approximate number of zine holdings.

Examples:

3421
500
null

Note: This is a manually maintained estimate, not automatically calculated.

established

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

Year the repository was established.

Examples:

"2003"
"1998"
"c. 1995"
""

status

Type: string (max 50 characters) Required: No Repeatable: No Default: "active"

Repository operational status.

Valid values:

active — Currently operating
inactive — Temporarily closed or on hiatus
defunct — Permanently closed

Examples:

"active"
"inactive"
"defunct"

Repository Types

Academic Library

University or college library.

Example:

{
  "repo_id": "repo_barnard_zine_library",
  "repository_name": "Barnard Zine Library",
  "repository_kind": "academic-library",
  "country": "US",
  "city": "New York",
  "marc_org_code": "NNC-Z",
  "isil": "US-NNC-Z",
  "website": "https://zines.barnard.edu",
  "status": "active"
}

Public Library

Municipal or regional public library.

Example:

{
  "repo_id": "repo_salt_lake_city_library",
  "repository_name": "Salt Lake City Public Library Zine Collection",
  "repository_kind": "public-library",
  "country": "US",
  "city": "Salt Lake City",
  "region": "UT",
  "website": "https://www.slcpl.org/zines",
  "status": "active"
}

Distro

Zine distribution organization.

Example:

{
  "repo_id": "repo_qzap",
  "repository_name": "Queer Zine Archive Project",
  "repository_kind": "distro",
  "country": "US",
  "city": "Milwaukee",
  "region": "WI",
  "website": "https://www.qzap.org",
  "description": "Community archive and lending library of queer zines.",
  "status": "active"
}

Community Archive

Grassroots community archive.

Example:

{
  "repo_id": "repo_abc_no_rio",
  "repository_name": "ABC No Rio Zine Library",
  "repository_kind": "community-archive",
  "country": "US",
  "city": "New York",
  "region": "NY",
  "description": "Volunteer-run zine library in Manhattan's Lower East Side.",
  "status": "active"
}

Personal Collection

Individual's personal collection.

Example:

{
  "repo_id": "repo_my_personal_collection",
  "repository_name": "My Personal Zine Collection",
  "repository_kind": "personal-collection",
  "country": "US",
  "city": "Seattle",
  "region": "WA",
  "established": "2015",
  "status": "active"
}

Defunct Repository

Repository that no longer exists.

Example:

{
  "repo_id": "repo_zinebook_defunct",
  "repository_name": "Zinebook (defunct)",
  "repository_kind": "distro",
  "country": "US",
  "city": "Portland",
  "region": "OR",
  "established": "2005",
  "status": "defunct",
  "description": "Closed in 2012. Collection donated to Portland State University Library."
}

Validation Errors

Missing Required Field

Response (400 Bad Request):

{
  "repo_id": ["This field is required."],
  "repository_name": ["This field is required."],
  "repository_kind": ["This field is required."],
  "country": ["This field is required."]
}

Invalid repository_kind

Request:

{
  "repository_kind": "invalid-kind"
}

Response (400 Bad Request):

{
  "repository_kind": ["Invalid repository kind: invalid-kind"]
}

Invalid Country Code

Request:

{
  "country": "USA"
}

Response (400 Bad Request):

{
  "country": ["Invalid country code. Must be ISO 3166-1 alpha-2 (e.g., 'US')"]
}

Code Examples

Python

import requests

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

# Create repository
repo_data = {
    "repo_id": "repo_my_library",
    "repository_name": "My Zine Library",
    "repository_kind": "personal-collection",
    "country": "US",
    "city": "Seattle",
    "region": "WA",
    "status": "active"
}

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

repo = response.json()
print(f"Created: {repo['repository_name']}")

# Get repository
repo = requests.get(f"{API_BASE}/repositories/repo_my_library/").json()
print(f"Name: {repo['repository_name']}")
print(f"City: {repo['city']}, {repo['region']}")

# Update repository
requests.patch(
    f"{API_BASE}/repositories/repo_my_library/",
    headers=headers,
    json={"holdings_count": 150}
)

JavaScript

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

// Create repository
const repoData = {
  repo_id: "repo_my_library",
  repository_name: "My Zine Library",
  repository_kind: "personal-collection",
  country: "US",
  city: "Seattle",
  status: "active"
};

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

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

// Get all US repositories
const usRepos = await fetch(
  `${API_BASE}/repositories/?country=US`
).then(r => r.json());

console.log(`Found ${usRepos.count} US repositories`);

Next Steps

Holdings API — Holdings endpoints reference
Zines API — Zines endpoints reference
Authentication — Token authentication guide

Edit this pageorReport an issue

Holdings API

Complete reference for the Holdings API endpoints

Authentication

Token authentication for ZineCore2 API write operations