API Documentation

Contents

Resources

API Versions

FreeDOI provides the following API versions:

Authentication

The FreeDOI API uses token-based authentication. You need to include your API token in the header of each request. 

Authorization: Token YOUR_API_TOKEN

You can generate or view your API token in your account settings.

API v1 Endpoints

GET /api/v1/dois/

List all DOIs owned by the authenticated user.

GET /api/v1/dois/{prefix.suffix/identifier}/

Get details of a specific DOI.

POST /api/v1/dois/

Create a new DOI.

PUT /api/v1/dois/{prefix.suffix/identifier}/

Update an existing DOI's target URL.

DELETE /api/v1/dois/{prefix.suffix/identifier}/

Delete a DOI.

Managing DOIs

List Your DOIs

GET /api/v1/dois/

Example Response

[
  {
    "doi": "20.1234/my-paper",
    "target_url": "https://example.com/papers/my-paper.pdf"
  },
  {
    "doi": "20.1234/another-paper",
    "target_url": "https://example.com/papers/another-paper.pdf"
  }
]

Get DOI Details

GET /api/v1/dois/20.1234/my-paper/

Example Response

{
  "doi": "20.1234/my-paper",
  "target_url": "https://example.com/papers/my-paper.pdf"
}

Create a DOI

POST /api/v1/dois/
Content-Type: application/json

{
  "doi": "20.1234/my-new-paper",
  "target_url": "https://example.com/papers/my-new-paper.pdf"
}

Note: DOI identifiers are case-insensitive. For example, "my-paper" and "My-Paper" are considered the same identifier.

Update a DOI's Target URL

PUT /api/v1/dois/20.1234/my-paper/
Content-Type: application/json

{
  "target_url": "https://new-location.com/papers/my-paper.pdf"
}

Delete a DOI

DELETE /api/v1/dois/20.1234/my-paper/

Usage Examples

For complete code examples in various programming languages, visit the Code Examples page.

Python Example

import requests

API_TOKEN = 'your_api_token'
BASE_URL = 'https://freedoi.org/api/v1'

headers = {
    'Authorization': f'Token {API_TOKEN}',
    'Content-Type': 'application/json'
}

# List your DOIs
response = requests.get(f'{BASE_URL}/dois/', headers=headers)
print(response.json())

# Create a new DOI
data = {
    'doi': '20.1234/my-new-paper',
    'target_url': 'https://example.com/papers/my-new-paper.pdf'
}
response = requests.post(f'{BASE_URL}/dois/', json=data, headers=headers)
print(response.json())

Legacy API (Deprecated)

Warning: The legacy API is deprecated and will be removed in a future version. Please use the v1 API instead.

The legacy API uses IDs instead of DOI strings, which makes it more complex to use. Documentation is provided here for reference only.

GET /api/suffixes/

List all suffixes owned by the authenticated user.

GET /api/suffixes/{id}/

Get details of a specific suffix.

GET /api/identifiers/

List all identifiers owned by the authenticated user.

GET /api/identifiers/{id}/

Get details of a specific identifier.

POST /api/identifiers/create/

Create a new identifier.

PUT /api/identifiers/{id}/update/

Update an existing identifier.