Skip to content

API Reference

Jump to bottom
aicoder2009 edited this page Jan 29, 2026 · 1 revision

API Reference

OpenCitation provides several API endpoints for citation lookup and management.

Lookup APIs

These endpoints extract metadata from various sources. No authentication required.

URL Lookup

Extract metadata from any URL using OpenGraph and meta tags.

GET /api/lookup/url?url={encoded_url}

Parameters:

Name Type Required Description
url string Yes URL-encoded web address

Response:

{
  "success": true,
  "data": {
    "title": "Article Title",
    "author": "Author Name",
    "siteName": "Website Name",
    "publishedDate": "2024-01-15",
    "description": "Article description...",
    "url": "https://example.com/article"
  }
}

DOI Lookup

Query CrossRef API for academic article metadata.

GET /api/lookup/doi?doi={doi}

Parameters:

Name Type Required Description
doi string Yes Digital Object Identifier (e.g., 10.1038/nature12373)

Response:

{
  "success": true,
  "data": {
    "title": "Article Title",
    "authors": [{"given": "John", "family": "Smith"}],
    "journal": "Nature",
    "volume": "500",
    "issue": "7461",
    "pages": "541-546",
    "publishedDate": "2013-08-29",
    "doi": "10.1038/nature12373"
  }
}

ISBN Lookup

Query Open Library (with Google Books fallback) for book metadata.

GET /api/lookup/isbn?isbn={isbn}

Parameters:

Name Type Required Description
isbn string Yes ISBN-10 or ISBN-13 (hyphens optional)

Response:

{
  "success": true,
  "data": {
    "title": "Book Title",
    "authors": ["Author Name"],
    "publisher": "Publisher Name",
    "publishedDate": "2020",
    "isbn": "9780140283297",
    "pages": 320
  }
}

Lists API

Manage citation lists. Authentication required.

Get All Lists

GET /api/lists

Response:

{
  "success": true,
  "data": [
    {
      "id": "list_abc123",
      "name": "Research Paper",
      "createdAt": "2024-01-15T10:30:00Z",
      "citationCount": 5
    }
  ]
}

Create List

POST /api/lists
Content-Type: application/json

{
  "name": "My New List"
}

Get List by ID

GET /api/lists/{id}

Update List

PUT /api/lists/{id}
Content-Type: application/json

{
  "name": "Updated Name"
}

Delete List

DELETE /api/lists/{id}

Citations API

Manage citations within lists. Authentication required.

Get Citations in List

GET /api/lists/{listId}/citations

Add Citation to List

POST /api/lists/{listId}/citations
Content-Type: application/json

{
  "sourceType": "book",
  "style": "apa",
  "data": {
    "title": "Book Title",
    "authors": [{"given": "John", "family": "Smith"}],
    "publisher": "Publisher",
    "year": "2024"
  },
  "formattedCitation": "Smith, J. (2024). Book Title. Publisher."
}

Delete Citation

DELETE /api/lists/{listId}/citations/{citationId}

Projects API

Manage projects. Authentication required.

Get All Projects

GET /api/projects

Create Project

POST /api/projects
Content-Type: application/json

{
  "name": "Fall 2024 Semester",
  "description": "All assignments for fall semester"
}

Get Project by ID

GET /api/projects/{id}

Add List to Project

POST /api/projects/{id}/lists
Content-Type: application/json

{
  "listId": "list_abc123"
}

Delete Project

DELETE /api/projects/{id}

Share API

Generate and access public share links.

Create Share Link

Authentication required.

POST /api/share
Content-Type: application/json

{
  "type": "list",
  "targetId": "list_abc123"
}

Response:

{
  "success": true,
  "shareCode": "abc123xyz",
  "shareUrl": "https://opencitation.vercel.app/share/abc123xyz"
}

Access Shared Content

No authentication required.

GET /api/share/{code}

Report Issue API

Submit issues to GitHub. No authentication required.

POST /api/report-issue
Content-Type: application/json

{
  "title": "Bug: Citation not formatting correctly",
  "description": "When I try to cite a website...",
  "issueType": "Bug",
  "email": "[email protected]"
}

Response:

{
  "success": true,
  "issueNumber": 42,
  "issueUrl": "https://github.com/aicoder2009/opencitation/issues/42"
}

Error Responses

All endpoints return errors in this format:

{
  "success": false,
  "error": "Error message description"
}

Common HTTP Status Codes:

Code Meaning
200 Success
400 Bad request (invalid parameters)
401 Unauthorized (authentication required)
404 Resource not found
500 Internal server error

Rate Limiting

Currently no rate limiting is enforced, but please be respectful of the service.

Questions?

Open an issue on GitHub for API-related questions.

Clone this wiki locally