---
id: api
title: Public API
---

# Public API

## API Endpoint: `https://public-api.gitpoap.io/`

<br />

If you have any questions, comments, or suggestions, please reach out in the #gitpoap channel of the POAP [Discord](https://discord.com/invite/fcxW4yR), or send us a message at team at gitpoap.io

<br />

## Version 1

**Note that the public API limits individual IPs to a
maximum of 100 requests within a 5 minute window.**

### `GET /v1/poap/:poapTokenId/is-gitpoap`

This endpoint allows users to query whether some `poapTokenId` is a GitPOAP or not.
In the case that the `poapTokenId` corresponds to some claimed GitPOAP, the API will return
something like:

```json
{
  "isGitPOAP": true,
  "gitPOAPId": 4003
}
```

And in the case that it is not a GitPOAP:

```json
{
  "isGitPOAP": false
}
```

<br />

### `GET /v1/poap/gitpoap-ids`

This endpoint returns all of the POAP Token IDs that are GitPOAPs. It will return data like:
```json
{
  "poapTokenIds": [
    "4637848",
    "4638134",
    "4641290",
    "4641645"
  ]
}
```

<br />

### `GET /v1/poap-event/:poapEventId/is-gitpoap`

This endpoint allows users to query whether some `poapEventId` is for GitPOAP project
contribution level. In the case that the `poapEventId` is for a GitPOAP project contribution
level, it will return something like:

```json
{
  "isGitPOAP": true,
  "gitPOAPId": 3001
}
```

And in the case that it is not a GitPOAP project contribution level:

```json
{
  "isGitPOAP": false
}
```

<br />

### `GET /v1/poap-event/gitpoap-event-ids`

This endpoint returns all of the POAP Event IDs that are GitPOAP Events. It will return data like:
```json
{
  "poapEventIds": [
    37428,
    37430,
    37556,
    37557
  ]
}
```

<br />

### `GET /v1/poap-event/gitpoap-event-fancy-ids`

This endpoint returns all of the POAP Event Fancy IDs that are GitPOAP Events. It will return data like:
```json
{
  "poapEventFancyIds": [
    "2022-wagyu-installer-contributor-2022",
    "2022-wagyu-key-gen-contributor-2022",
    "gitpoap-2015-truffle-contributor-2015",
    "gitpoap-2016-truffle-contributor-2016"
  ]
}
```

<br />

### `GET /v1/gitpoaps/events`

This endpoint allows user to query for information on all the GitPOAPs that have been released so far. It will return data in the form:
```json
{
  "gitPoapEvents": [{
    "gitPoapEventId": 32423,
    "poapEventId": 343,
    "poapEventFancyId": "gitpoap-gitpoap-docs-level-2-contributor-2022",
    "name": "GitPOAP: gitpoap-docs Level 2 Contributor 2022",
    "year": 2022,
    "description": "You've made at least 5 contributions to the gitpoap-docs project in 2022!",
    "imageUrl": "https://assets.poap.xyz/gitpoap-2022-devconnect-hackathon-gitpoap-team-contributor-2022-logo-1650466033470.png",
    "repositories": ["gitpoap/gitpoap-docs"],
    "mintedCount": 5,
  }]
}
```

<br />

### `GET /v1/gitpoaps/:gitPoapEventId/addresses`

This endpoint allows users to query for a list of addresses that hold a GitPOAP specified by GitPOAP Event ID. It returns something like:

```json
{
  "addresses": [
    "0x4b412F5eF87A2F85Fc8C6f90728d2D03941aFd80",
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  ]
}
```

If there are no holders, it returns something like:

```json
{
  "addresses": []
}
```

And in the case that no GitPOAP with that ID is found, it returns the following with a 404:

```json
{
  "message": "GitPOAP not found"
}
```

<br />

### `GET /v1/gitpoaps/addresses`

This endpoint allows users to query for a list of all addresses that hold any GitPOAP. It returns something like:

```json
{
  "addresses": [
    "0x4b412F5eF87A2F85Fc8C6f90728d2D03941aFd80",
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "0x02738d122e0970aAf8DEADf0c6A217a1923E1e99",
    "0xae95f7e7fb2fcf86148ef832faed2752ae5a358a"
  ]
}
```

<br />

### `GET /v1/address/:address/gitpoaps`

This endpoint allows users to query for some address's (either an ETH or ENS address) GitPOAPs. This returns data like:

```json
[
  {
    "gitPoapId": 2,
    "gitPoapEventId": 1,
    "poapTokenId": "4638134",
    "poapEventId": 37428,
    "poapEventFancyId": "2022-wagyu-installer-contributor",
    "name": "2022 Wagyu Installer Contributor",
    "year": 2022,
    "description": "You contributed at least one merged pull request to the Wagyu Installer project in 2022.  Your contributions are greatly valued.",
    "imageUrl": "https://assets.poap.xyz/2022-wagyu-installer-contributor-2022-logo-1649213116205.png",
    "repositories": ["stake-house/wagyu-installer"],
    "earnedAt": "2022-01-20",
    "mintedAt": "2022-04-06"
  }
]
```

<br />

### `GET /v1/github/user/:githubHandle/gitpoaps?status=<status>`

This endpoint allows users to query for minted GitPOAPs associated with a specified GitHub handle. The `status` query parameter is one of
the following: `claimed`, `unclaimed`, `pending`, `minting`, and can be omitted completely. This returns data like:

```json
[
  {
    "gitPoapId": 34,
    "gitPoapEventId": 32423,
    "poapTokenId": "2432",
    "poapEventId": 343,
    "poapEventFancyId": "gitpoap-gitpoap-docs-level-2-contributor-2022",
    "name": "GitPOAP: gitpoap-docs Level 2 Contributor 2022",
    "year": 2022,
    "description": "You've made at least 5 contributions to the gitpoap-docs project in 2022!",
    "imageUrl": "https://assets.poap.xyz/gitpoap-2022-devconnect-hackathon-gitpoap-team-contributor-2022-logo-1650466033470.png",
    "repositories": ["gitpoap/gitpoap-docs"],
    "earnedAt": "2022-04-25",
    "mintedAt": "2022-05-22"
  }
]
```

<br />

### `GET /v1/repo/:owner/:name/badge`

This endpoint generates a GitHub badge containing the count of minted GitPOAPs for a specified repo. The repo is specified with a GitHub owner and repo name & the endpoint will return a SVG for use in any `.md` file such as a `README.md`.

Using `ethereum/ethereum-org-website` as an example via [https://public-api.gitpoap.io/v1/repo/ethereum/ethereum-org-website/badge](https://public-api.gitpoap.io/v1/repo/ethereum/ethereum-org-website/badge), embed the badge in a `.md` file the following way:

```markdown
[![GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/gitpoap/gitpoap-docs/badge)](https://www.gitpoap.io/gh/gitpoap/gitpoap-docs)
```

Resulting in the following:

[![GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/gitpoap/gitpoap-docs/badge)](https://www.gitpoap.io/gh/gitpoap/gitpoap-docs)