Skip to main content

Quick Start

This guide will help you make your first API request to Pinboard.

Prerequisites​

  • A Pinboard account
  • Access to a team in Pinboard

Step 1: Get Your API Token​

  1. Log in to the Pinboard app at pinboard.ai
  2. Your session will automatically generate a JWT token
  3. Use the token exchange endpoint to get an API token
curl -X POST https://api.pinboard.ai/api/v1/auth/token/exchange \
  -H "Content-Type: application/json" \
  -d '{"sessionToken": "your-nextauth-session-token"}'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "bearer",
  "expiresIn": 86400
}

Step 2: Make Your First Request​

Use the access token to authenticate API requests:

curl https://api.pinboard.ai/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "id": "user-123",
  "email": "you@example.com",
  "username": "yourname",
  "name": "Your Name",
  "siteRole": "user"
}

Step 3: List Your Teams​

curl https://api.pinboard.ai/api/v1/teams \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "teams": [
    {
      "id": "team-123",
      "name": "My Team",
      "slug": "my-team",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Step 4: List Projects in a Team​

curl https://api.pinboard.ai/api/v1/teams/team-123/projects \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Next Steps​

Code Examples​

JavaScript/TypeScript​

const response = await fetch('https://api.pinboard.ai/api/v1/teams', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data.teams);

Python​

import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',
}

response = requests.get('https://api.pinboard.ai/api/v1/teams', headers=headers)
data = response.json()
print(data['teams'])

cURL​

curl -X GET "https://api.pinboard.ai/api/v1/teams" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"