Features

Authorization

The patreon API is only accessible by using Oauth. You can choose between two types of applications:

• Creator account
• User Oauth

For both types of applications you will need to create a client in the developer portal. Copy the client id and secret and store them in your secrets. You can also find the creator access and refresh tokens in the client information.

Request

When you have created the application, you're ready to make a request.

NOTE

In API v2, all attributes must be explicitly requested.

You can use the methods on the client:

Client example

import { type PatreonClient, QueryBuilder } from 'patreon-api.ts'

export async function fetchPatreon (client: PatreonClient) {
    // Get the full name of the creator of the campaign
    const query = QueryBuilder.campaigns
        .addRelationships(['creator'])
        .addRelationshipAttributes('creator', ['full_name'])

    // get the campaigns
    const campaigns = await client.fetchCampaigns(query)
    // or fetch the post(s), member(s), post(s) or current user

    // Or list resources to paginate multiple pages
    for await (const campaigns of client.paginateCampaigns(query)) {
        for (const campaign of campaigns.data) {
            const creatorId = campaign.relationships.creator.data?.id
            const creator = campaigns.included.find(t => t.id === creatorId)

            console.log(`Campaign ${campaign.id} is created by ${creator?.attributes.full_name}`)
        }
    }
}

Raw example

import { type PatreonClient, QueryBuilder, Routes, Type, type PatreonQuery } from 'patreon-api.ts'

export async function fetchPatreonRaw (client: PatreonClient) {
    type Query = PatreonQuery<Type.Campaign, 'creator', {
        user: ('full_name')[]
    }, true>

    const query = QueryBuilder.fromParams<Query>(new URLSearchParams({
        include: 'creator',
        'fields[user]': 'full_name',
    }))

    // get the campaigns
    const campaigns = await client.fetchOauth2(Routes.campaigns(), query)
    // or fetch the post(s), member(s), post(s) or current user

    // Or list resources to paginate multiple pages
    for await (const campaigns of client.paginateOauth2(Routes.campaigns(), query)) {
        for (const campaign of campaigns.data) {
            console.log(campaign.id)
        }
    }
}

Tip

My advice is to write your own wrapper / class that uses a client with all attributes and included resources configured. If you need all the relationships and attributes, you can also use the client option includeAllQueries (see example above).

Custom wrapper

import { PatreonCreatorClient } from 'patreon-api.ts'

declare const env: {
    CLIENT_ID: string
    CLIENT_SECRET: string
}

export class Patreon {
    public client: PatreonCreatorClient<true>
    public campaignId: string

    public constructor (campaignId: string) {
        this.campaignId = campaignId

        this.client = new PatreonCreatorClient({
            oauth: {
                clientId: env.CLIENT_ID,
                clientSecret: env.CLIENT_SECRET,
            },
            rest: {
                includeAllQueries: true,
            },
        })
    }

    public async fetch () {
        return await this.client.simplified.fetchCampaign(this.campaignId)
    }

    public async fetchMembers () {
        return await this.client.simplified.fetchCampaignMembers(this.campaignId)
    }

    public async fetchPosts () {
        return await this.client.simplified.fetchCampaignPosts(this.campaignId)
    }
}

Custom client

import { PatreonClient } from 'patreon-api.ts'

// Can also extend a creator or user client
export class MyCampaignClient extends PatreonClient {
    public campaignId: string = '<id>'

    public async fetch () {
        return await this.fetchCampaign(this.campaignId)
    }
}

Responses

When fetching a resource the response is a JSON:API response and is typed based on the query, see the introduction.

You can also normalize responses to connect the relationships and included items.

Testing

Not ready to connect your Patreon account to your application? Test your app with the sandbox with sample payloads.