TUM Research Information API

Overview

This API provides access to publication and project data from the TUM research information system (Pure). You can retrieve publications and projects associated with specific organizations or persons, with optional filtering by type.

Available Data

Publications and projects count only what the API returns (see the notes on each endpoint); authors and organizations count all synced records.

Pagination

/publications and /projects are paginated: 50 items per page by default, at least 10 and at most 100 (per_page). page is capped at 10000. Invalid or out-of-range page/per_page values don't cause an error: a non-numeric value falls back to the default and other values are clamped; the pagination object in the response shows the values used. A page past the last page returns 404. Results are sorted with a stable tie-breaker, so walking the pages neither skips nor repeats records. /publication-types is not paginated.

Caching

Successful responses carry an ETag. Send it back in If-None-Match and you get 304 Not Modified without a body if nothing changed. Cache-Control is private, max-age=60, stale-while-revalidate=300 for /publications and /projects and private, max-age=3600, stale-while-revalidate=86400 for /publication-types; errors are sent with no-store. The server also caches results: up to 5 minutes for publications and projects (the availableTypes list up to 15 minutes), up to 24 hours for /publication-types, so changes in Pure can take that long to appear after they have been synced.

Rate Limits

Requests are limited per API token in fixed 60-second windows (60 requests per minute unless the operator configured otherwise). Over the limit you get 429 with a Retry-After header giving the seconds until the window resets. Repeated failed authentication from one IP address is limited the same way. The search tools on this page are limited per IP address, and the API Tester to 20 requests per minute per IP address.

Methods and CORS

All endpoints are read-only and accept GET and HEAD; other methods get 405 with an Allow: GET, HEAD header. Browsers can call /publications, /projects and /publication-types from the allowed origins (HTTPS pages on the configured domains and their subdomains, plus http://localhost); the CORS preflight (OPTIONS) is answered with 204 without a token.

Authentication

/publications, /projects, /publication-types and /metrics require authentication using a Bearer token. You must include the token in the Authorization header of every request to them. /health and this documentation page need no token.

Using Your Token

Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC"

Error Responses

All 401 responses include a WWW-Authenticate: Bearer header.

API Endpoints

{
    "orgTumIds": ["TUS1ABC"],            // or "personTumIds" depending on 'by' parameter
                                         // Array of successfully found TUM IDs
    "pagination": {
        "page": 1,
        "per_page": 50,
        "total": 150,
        "total_pages": 3
    },
    "count": 50,                         // Number of publications in current page
    "sort": "year",                      // active sort field
    "order": "desc",                     // active sort direction
    "availableTypes": ["Article", "Chapter", "Conference contribution"],
                                         // distinct publication types in the filtered set
                                         // (ignores the active type filter, so consumers can switch)
    "filteredByType": "Article",         // only present if type filter was used
    "filteredByKeywords": "machine learning",  // only present if the keywords filter was applied
    "filteredByYear": 2024,              // only present if year filter was used
    "notFoundIds": ["TUS9XYZ"],          // only present if some (not all) IDs were not found
    "publications": [
        {
            "uuid": "12345678-1234-1234-1234-123456789abc",
            "typeDiscriminator": "JournalArticle",
            "title": "Publication Title",
            "subTitle": "Optional Subtitle",
            "abstract": "This paper presents...",
            "keywords": "machine learning; artificial intelligence; healthcare",
            "type": "Article",
            "publicationStatus": "Published",   // Pure's current publication status
            "publicationDate": 2024,             // year of that status (integer); the year filter matches it
            "authors": "Smith, John; Doe, Jane",
            "doi": "10.1234/example.2024.001",
            "pages": "1-15",
            "articleNumber": "e12345",
            "numberOfPages": 15,
            "volume": "42",
            "journalNumber": "3",
            "journalTitle": "Journal of Example Research",
            "issn": "1234-5678",
            "isbn": "978-3-16-148410-0",
            "publisher": "Springer Nature",
            "peerReview": 1,                     // 1, 0, or null if Pure doesn't say
            "openAccess": "Gold",
            "patentNumber": null,            // patent-specific (null for non-patents)
            "ipc": null,                     // patent-specific, IPC codes joined with "; "
            "patentDate": null,              // patent filing/grant date (YYYY-MM-DD)
            "priorityDate": null,            // patent priority date (YYYY-MM-DD)
            "priorityNumber": null,          // patent priority application number
            "country": null,                 // patent jurisdiction (e.g., "Germany")
            "url": "https://portal.fis.tum.de/en/publications/12345678-1234-1234-1234-123456789abc"
        }
    ]
}

{
    "count": 15,
    "types": [
        "Article",
        "Book",
        "Conference",
        "Contribution to Book/Anthology",
        "Patent",
        "Thesis",
        "..."
    ]
}

{
    "orgTumIds": ["TUS1ABC"],     // or "personTumIds" depending on 'by' parameter
                                  // Array of successfully found TUM IDs
    "pagination": {
        "page": 1,
        "per_page": 50,
        "total": 75,
        "total_pages": 2
    },
    "count": 50,                  // Number of projects in current page
    "sort": "year",               // active sort field
    "order": "desc",              // active sort direction
    "filteredByType": "Research", // only present if type filter was used
    "filteredByYear": 2024,       // only present if year filter was used
    "notFoundIds": ["TUS9XYZ"],   // only present if some (not all) IDs were not found
    "projects": [
        {
            "uuid": "...",
            "title": "Project Title",
            "description": "Project description...",
            "type": "Research",
            "startDate": "2020-01-01",
            "endDate": "2023-12-31",
            "managingOrgUuid": "...",              // UUID of the managing organization
            "url": "https://gepris.dfg.de/...",    // first external link in Pure (may be empty)
            "portalUrl": "https://portal.fis.tum.de/en/projects/..."
        }
    ]
}

// 200 OK
{"status": "healthy", "checks": {"database": "up"}}

// 503 Service Unavailable
{"status": "unhealthy", "checks": {"database": "down"}}

Tools

Usage Examples

GET https://fisapi.it.tum.de/publication-types

GET https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC

GET https://fisapi.it.tum.de/publications?by=person&tumId=go42tum

GET https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC,TUS2DEF

GET https://fisapi.it.tum.de/publications?by=person&tumId=go42tum,ab12tum

GET https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&type=Article

GET https://fisapi.it.tum.de/publications?by=person&tumId=go42tum&type=Conference

GET https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&keywords=machine%20learning

GET https://fisapi.it.tum.de/publications?by=person&tumId=go42tum&type=Article&keywords=AI

GET https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&year=2024

GET https://fisapi.it.tum.de/projects?by=org&tumId=TUS1ABC&year=2024

GET https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&sort=title&order=asc

GET https://fisapi.it.tum.de/projects?by=org&tumId=TUS1ABC&sort=year&order=asc

GET https://fisapi.it.tum.de/projects?by=org&tumId=TUS1ABC

GET https://fisapi.it.tum.de/projects?by=person&tumId=go42tum

GET https://fisapi.it.tum.de/projects?by=org&tumId=TUS1ABC,TUS2DEF

GET https://fisapi.it.tum.de/projects?by=person&tumId=go42tum,ab12tum

GET https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&page=2

GET https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&per_page=25

GET https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&type=Article&page=3&per_page=20

JavaScript Example

// API token - replace with your actual token
const API_TOKEN = 'YOUR_API_TOKEN';

// Helper function to make authenticated requests
async function apiFetch(url) {
    const response = await fetch(url, {
        headers: {
            'Authorization': `Bearer ${API_TOKEN}`
        }
    });
    if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
    }
    return response.json();
}

// Fetch all available publication types
async function getPublicationTypes() {
    const url = 'https://fisapi.it.tum.de/publication-types';
    const data = await apiFetch(url);

    console.log(`Found ${data.count} publication types`);
    return data.types;
}

// Example usage
getPublicationTypes()
    .then(types => {
        console.log('Available types:', types);
    });

// Fetch publications for one or more organizations
async function getOrgPublications(orgTumIds, options = {}) {
    // orgTumIds can be a string or an array
    const ids = Array.isArray(orgTumIds) ? orgTumIds.join(',') : orgTumIds;
    let url = `https://fisapi.it.tum.de/publications?by=org&tumId=${ids}`;

    if (options.type) {
        url += `&type=${encodeURIComponent(options.type)}`;
    }
    if (options.keywords) {
        url += `&keywords=${encodeURIComponent(options.keywords)}`;
    }
    if (options.year) {
        url += `&year=${encodeURIComponent(options.year)}`;
    }
    if (options.sort) {
        url += `&sort=${encodeURIComponent(options.sort)}`;
    }
    if (options.order) {
        url += `&order=${encodeURIComponent(options.order)}`;
    }
    if (options.page) {
        url += `&page=${options.page}`;
    }
    if (options.per_page) {
        url += `&per_page=${options.per_page}`;
    }

    const data = await apiFetch(url);

    console.log(`Found ${data.pagination.total} total publications`);
    console.log(`Page ${data.pagination.page} of ${data.pagination.total_pages}`);
    if (data.notFoundIds && data.notFoundIds.length > 0) {
        console.log(`Not found: ${data.notFoundIds.join(', ')}`);
    }
    return data;
}

// Example usage - single organization with type filter
getOrgPublications('TUS1ABC', { type: 'Article' })
    .then(data => {
        data.publications.forEach(pub => {
            console.log(`${pub.title} (${pub.publicationDate})`);
        });
    });

// Example usage - filter by keywords with pagination
getOrgPublications('TUS1ABC', { keywords: 'machine learning', page: 1, per_page: 25 })
    .then(data => {
        console.log(`Showing ${data.count} of ${data.pagination.total} results`);
        data.publications.forEach(pub => {
            console.log(`${pub.title} - Keywords: ${pub.keywords}`);
        });
    });

// Example usage - combine type and keywords filters with pagination
getOrgPublications('TUS1ABC', { type: 'Article', keywords: 'AI', page: 2 })
    .then(data => {
        data.publications.forEach(pub => {
            console.log(`${pub.title} (${pub.publicationDate})`);
        });
    });

cURL Example

# Set your API token (replace with your actual token)
TOKEN="YOUR_API_TOKEN"

# Get all available publication types
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publication-types"

# Get all publications for an organization
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC"

# Get publications from multiple organizations
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC,TUS2DEF"

# Get only journal articles
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&type=Article"

# Filter by keywords
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&keywords=machine%20learning"

# Combine type and keywords filters
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=person&tumId=go42tum&type=Article&keywords=AI"

# Filter publications by year
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&year=2024"

# Filter projects by start year
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/projects?by=org&tumId=TUS1ABC&year=2024"

# Sort publications alphabetically by title
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&sort=title&order=asc"

# Sort projects by year ascending
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/projects?by=org&tumId=TUS1ABC&sort=year&order=asc"

# Get publications for a person
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=person&tumId=go42tum"

# Get publications from multiple persons
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=person&tumId=go42tum,ab12tum"

# Get all projects for an organization
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/projects?by=org&tumId=TUS1ABC"

# Get projects from multiple organizations
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/projects?by=org&tumId=TUS1ABC,TUS2DEF"

# Get projects for a person
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/projects?by=person&tumId=go42tum"

# Get projects from multiple persons
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/projects?by=person&tumId=go42tum,ab12tum"

# Get second page of publications (50 per page by default)
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&page=2"

# Get 25 publications per page
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&per_page=25"

# Combine pagination with filters
curl -H "Authorization: Bearer $TOKEN" \
     "https://fisapi.it.tum.de/publications?by=org&tumId=TUS1ABC&type=Article&page=3&per_page=20"

PHP Example

// API token - replace with your actual token
define('API_TOKEN', 'YOUR_API_TOKEN');

// Helper function to make authenticated API requests
function apiFetch($url) {
    $context = stream_context_create([
        'http' => [
            'header' => 'Authorization: Bearer ' . API_TOKEN
        ]
    ]);
    $response = file_get_contents($url, false, $context);
    return json_decode($response, true);
}

// Fetch all available publication types
function fetchPublicationTypes() {
    $url = 'https://fisapi.it.tum.de/publication-types';
    $data = apiFetch($url);
    return $data['types'];
}

// Example usage
$types = fetchPublicationTypes();
echo "Available publication types:\n";
foreach ($types as $type) {
    echo "- $type\n";
}

// Fetch publications using PHP
function fetchPublications($tumIds, $by = 'org', $options = []) {
    $baseUrl = 'https://fisapi.it.tum.de/publications';

    // Handle both string and array inputs
    $ids = is_array($tumIds) ? implode(',', $tumIds) : $tumIds;

    $params = [
        'tumId' => $ids,
        'by' => $by
    ];

    if (!empty($options['type'])) {
        $params['type'] = $options['type'];
    }

    if (!empty($options['keywords'])) {
        $params['keywords'] = $options['keywords'];
    }

    if (!empty($options['year'])) {
        $params['year'] = $options['year'];
    }

    if (!empty($options['sort'])) {
        $params['sort'] = $options['sort'];
    }

    if (!empty($options['order'])) {
        $params['order'] = $options['order'];
    }

    if (!empty($options['page'])) {
        $params['page'] = $options['page'];
    }

    if (!empty($options['per_page'])) {
        $params['per_page'] = $options['per_page'];
    }

    $url = $baseUrl . '?' . http_build_query($params);

    return apiFetch($url);
}

// Example usage - single organization with type filter
$data = fetchPublications('TUS1ABC', 'org', ['type' => 'Article']);
echo "Found " . $data['pagination']['total'] . " articles total\n";
echo "Showing page " . $data['pagination']['page'] . " of " . $data['pagination']['total_pages'] . "\n";

foreach ($data['publications'] as $pub) {
    echo "- " . $pub['title'] . "\n";
}

// Example usage - filter by keywords with pagination
$data = fetchPublications('TUS1ABC', 'org', [
    'keywords' => 'machine learning',
    'page' => 1,
    'per_page' => 25
]);
echo "Found " . $data['pagination']['total'] . " publications about machine learning\n";
echo "Showing " . $data['count'] . " results on this page\n";

foreach ($data['publications'] as $pub) {
    echo "- " . $pub['title'] . " (Keywords: " . $pub['keywords'] . ")\n";
}

// Example usage - combine type and keywords filters with pagination
$data = fetchPublications('TUS1ABC', 'org', [
    'type' => 'Article',
    'keywords' => 'AI',
    'page' => 2
]);
echo "Page 2 - Found " . $data['count'] . " articles about AI\n";

Error Responses

Errors are JSON objects of the form {"error": "<message>"}, sent with Cache-Control: no-store. Some add fields, as noted below. Method and authentication checks (405, 401, 429, 503) run first; the parameter checks run in the order listed.

API Tester and Search Tools

The tools on this page return these additional errors:

Otherwise the API Tester shows the API's own response, including its status code.