> ## Documentation Index
> Fetch the complete documentation index at: https://developers.openalex.org/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> OpenAlex REST API fundamentals

The OpenAlex API provides access to a comprehensive catalog of scholarly works, authors, sources, institutions, topics, and more.

<Note>
  **New to OpenAlex?** Start with the [Guides](/index) for tutorials and walkthroughs. This API Reference is for detailed endpoint documentation.
</Note>

## Base URL

```
https://api.openalex.org
```

## Authentication

Add your API key as a query parameter:

```bash theme={"dark"}
curl "https://api.openalex.org/works?api_key=YOUR_KEY"
```

<Note>
  API keys are free. [Get yours here](https://openalex.org/settings/api). See [Authentication & Pricing](/guides/authentication) for details.
</Note>

## Entities

The API is organized around these entity types:

| Entity                                                | Endpoint             | Description                                     |
| ----------------------------------------------------- | -------------------- | ----------------------------------------------- |
| [Works](/api-reference/works)                         | `/works`             | Scholarly documents (articles, books, datasets) |
| [Authors](/api-reference/authors)                     | `/authors`           | Researchers with disambiguated identities       |
| [Sources](/api-reference/sources)                     | `/sources`           | Journals, repositories, conferences             |
| [Institutions](/api-reference/institutions)           | `/institutions`      | Universities, research organizations            |
| [Topics](/api-reference/topics)                       | `/topics`            | Research area classifications                   |
| [Keywords](/api-reference/keywords)                   | `/keywords`          | Short phrases from works                        |
| [Publishers](/api-reference/publishers)               | `/publishers`        | Publishing organizations                        |
| [Funders](/api-reference/funders)                     | `/funders`           | Funding agencies                                |
| [Awards](/api-reference/awards)                       | `/awards`            | Research grants                                 |
| [Domains](/api-reference/domains)                     | `/domains`           | Top-level topic hierarchy                       |
| [Fields](/api-reference/fields)                       | `/fields`            | Second-level topic hierarchy                    |
| [Subfields](/api-reference/subfields)                 | `/subfields`         | Third-level topic hierarchy                     |
| [SDGs](/api-reference/sdgs)                           | `/sdgs`              | UN Sustainable Development Goals                |
| [Countries](/api-reference/countries)                 | `/countries`         | Geographic entities                             |
| [Continents](/api-reference/continents)               | `/continents`        | Geographic entities                             |
| [Languages](/api-reference/languages)                 | `/languages`         | Language classifications                        |
| [Work Types](/api-reference/work-types)               | `/work-types`        | Enumeration of work types                       |
| [Source Types](/api-reference/source-types)           | `/source-types`      | Enumeration of source types                     |
| [Institution Types](/api-reference/institution-types) | `/institution-types` | Enumeration of institution types                |
| [Licenses](/api-reference/licenses)                   | `/licenses`          | Enumeration of licenses                         |
| [Concepts](/api-reference/concepts)                   | `/concepts`          | Legacy taxonomy (deprecated)                    |

## Operations

Each entity supports these operations:

| Operation                     | Pattern                     | Example                                   |
| ----------------------------- | --------------------------- | ----------------------------------------- |
| List                          | `GET /{entities}`           | `GET /works`                              |
| [Get](/guides/get)            | `GET /{entities}/{id}`      | `GET /works/W2741809807`                  |
| [Filter](/guides/filtering)   | `GET /{entities}?filter=`   | `GET /works?filter=publication_year:2024` |
| [Search](/guides/searching)   | `GET /{entities}?search=`   | `GET /works?search=machine+learning`      |
| [Aggregate](/guides/grouping) | `GET /{entities}?group_by=` | `GET /works?group_by=type`                |

## Response Format

All list endpoints return the same structure:

```json theme={"dark"}
{
  "meta": {
    "count": 286750097,
    "db_response_time_ms": 152,
    "page": 1,
    "per_page": 25
  },
  "results": [
    { "id": "https://openalex.org/W2741809807", "title": "...", ... },
    { "id": "https://openalex.org/W2741809808", "title": "...", ... }
  ],
  "group_by": []
}
```

| Field           | Description                                 |
| --------------- | ------------------------------------------- |
| `meta.count`    | Total results matching your query           |
| `meta.page`     | Current page number                         |
| `meta.per_page` | Results per page (default 25, max 100)      |
| `results`       | Array of entity objects                     |
| `group_by`      | Aggregation results (when using `group_by`) |

## Quick Example

Get open access articles from 2024 with more than 100 citations:

```bash theme={"dark"}
curl "https://api.openalex.org/works?filter=publication_year:2024,is_oa:true,cited_by_count:>100&per_page=10&api_key=YOUR_KEY"
```

## Query Parameters

| Parameter  | Description              |
| ---------- | ------------------------ |
| `api_key`  | Your API key (required)  |
| `filter`   | Filter by field values   |
| `search`   | Full-text search         |
| `sort`     | Sort results             |
| `per_page` | Results per page (1-100) |
| `page`     | Page number              |
| `cursor`   | Deep pagination cursor   |
| `sample`   | Random sample size       |
| `select`   | Limit returned fields    |
| `group_by` | Aggregate by field       |

## External IDs

Look up entities by external identifiers:

```bash theme={"dark"}
# By DOI
GET /works/https://doi.org/10.7717/peerj.4375
GET /works/doi:10.7717/peerj.4375

# By ORCID
GET /authors/https://orcid.org/0000-0001-6187-6610

# By ROR
GET /institutions/https://ror.org/0161xgx34

# By PMID
GET /works/pmid:29456894
```

## OpenAPI Specification

The complete API specification is available for tooling and code generation:

<Card title="OpenAPI Spec" icon="code" href="/api-reference/openapi.json">
  Download the OpenAPI 3.1 specification
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/guides/authentication">
    API keys, pricing, and rate limits
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api-reference/errors">
    Status codes and retry strategies
  </Card>

  <Card title="Key Concepts" icon="lightbulb" href="/guides/key-concepts">
    IDs, dehydrated objects, and data model
  </Card>

  <Card title="LLM Reference" icon="robot" href="/guides/llm-quick-reference">
    Optimized reference for AI agents
  </Card>
</CardGroup>