# Introduction/Getting Started

## Base URL

> <https://data-sources-v2.pdap.io/api> ← builds from main branch
>
> <https://data-sources-v2.pdap.dev/api> ← builds from dev branch

## Endpoints & Models

Navigate to either base URL above to see the API and model reference for v2 API on either the `main` or `dev` branch.

This documentation assumes you are familiar with programming languages such as Python, as well as the big-picture functionality of the API. For a more thorough breakdown of the functionality of an API, consider documentation such as Postman's [Beginner's Guide to APIs](https://www.postman.com/what-is-an-api/#how-do-apis-work).

Reach out to <contact@pdap.io> or make noise in [Discord](https://discord.gg/wMqex8nKZJ) if you have questions.

## Overview

The PDAP API is how internal and external users programmatically access information and make changes to the PDAP Data Sources database.

## Getting Access

Logged-in and authenticated users can get access to the API.

## Authentication

The majority of API routes require one of two forms of Authentication: API Tokens, and JSON Web Tokens (JWTs). A limited number of endpoints allow one or the other.

#### API Tokens

* API tokens are long-lived tokens used for endpoints with low security needs that do not modify existing data, such as `GET` requests.
* API tokens can be passed to accepting endpoints using `Basic` authorization (i.e., `Basic <TokenName>`).
* API tokens can be obtained by using the `/api-key` endpoint and generating login credentials
* API tokens are long-lived, and users can only have one active at a time.

#### JSON Web Tokens (JWTs)

* [JWTs](https://en.wikipedia.org/wiki/JSON_Web_Token) are short-lived encrypted tokens used for more secure endpoints
* JWTs can be passed to accept endpoints using `Bearer` authorization (i.e. `Bearer <TokenName>`)
* An `access_token` and `refresh_token` are both generated by the `/login` and `/login-with-github` endpoints
  * The access token is the token to be used for most endpoints
* Separate single-purpose JWTs are used for specific endpoints, such as `/reset-password`

## Rate limits

Different endpoints have different rate limits to them, with endpoints like `/data-sources/{resource_id}` `GET` Being more generous than endpoints such as `/login`. This helps prevent abuse of the system, and should minimally impact normal usage.

## Examples

{% tabs %}
{% tab title="Python" %}
**GET Agencies**

```python
import requests
base_url = "https://data-sources-v2.pdap.io/"
api_key = "YOUR_API_KEY_HERE"  # Replace with your actual API key

url = f"{base_url}agencies"

# Create the Authorization header
headers = {
    "Authorization": f"Bearer {api_key}"
}

# Make the GET request with the Authorization header
response = requests.get(url, headers=headers)
```

{% endtab %}

{% tab title="JavaScript" %}

#### GET agencies

```javascript
const axios = require('axios');

const baseUrl = "https://data-sources-v2.pdap.io/";
const api_key = "YOUR_API_KEY_HERE";  // Replace with your actual API key

const url = `${baseUrl}agencies`;

// Create the Authorization header
const headers = {
  'Authorization': `Bearer ${api_key}`
};

// Make the GET request with the Authorization header
axios.get(url, { headers })
  .then(response => {
    console.log("Search results:");
    response.data.forEach(item => {
      console.log(`Agency: ${item.name}`);
    });
  })
  .catch(error => {
      console.error("An error occurred:", error.message);
    }
  });
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pdap.io/api/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.