Void Presence API endpoints

API overview

Use these HTTP endpoints to fetch presence configs and status cycles directly from Void Presence.

All responses are JSON and designed to be copy-pastable into your own tools or scripts.

API resources

Endpoints cover presence configs, status cycles and authentication helpers.

Use them from your own tools or backend services to integrate with Void Presence.

Authentication

Most public endpoints do not require authentication.

You can inspect all HTTP API references directly in the web source.

View API references on GitHub

Rate limits & usage

Avoid polling these endpoints aggressively from public clients.

Prefer calling them from your own backend or tools when possible.

22 endpoints found

API endpoints

/v1/authors/resolveGET

Public

Resolve author by username and tag

Resolves author profile and configs by username and tag. Query: ?username=User&tag=1234. Used by /profile/{username}?tag=XXXX.

https://api.voidpresence.site/v1/authors/resolve Copy URL

JSON responseHas example

fetch('https://api.voidpresence.site/v1/authors/resolve?username=Author%20Name&tag=1234')
  .then(res => res.json())
  .then(data => console.log(data))

{
  "user": {
    "name": "Author Name",
    "avatar": "https://example.com/avatar.png",
    "tag": "1234",
    "provider": "discord",
    "createdAt": 123456789,
    "lastSeen": 123456789
  },
  "presenceConfigs": [],
  "statusConfigs": []
}

/v1/authors/resolvePOST

Public

Resolve author by username and tag (JSON)

Same as GET /v1/authors/resolve but accepts JSON body { username, tag } instead of query parameters.

https://api.voidpresence.site/v1/authors/resolve Copy URL

JSON responseHas example

fetch('https://api.voidpresence.site/v1/authors/resolve', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'Author Name', tag: '1234' }),
})
  .then(res => res.json())
  .then(data => console.log(data))

{
  "requestBody": {
    "username": "Author Name",
    "tag": "1234"
  },
  "responseBody": {
    "user": {
      "name": "Author Name",
      "avatar": "https://example.com/avatar.png",
      "tag": "1234",
      "provider": "discord",
      "createdAt": 123456789,
      "lastSeen": 123456789
    },
    "presenceConfigs": [],
    "statusConfigs": []
  }
}

/api/v1/authors/streamGET

Public

Stream author configs by handle

Streams live updates for an author profile and their configs via SSE, resolved by username and tag. Query: username=User&tag=1234. Events: ready, update, not-found, ping.

https://voidpresence.site/api/v1/authors/stream Copy URL

JSON responseHas example

const es = new EventSource('https://voidpresence.site/api/v1/authors/stream?username=Author%20Name&tag=1234')

es.addEventListener('ready', event => {
  const data = JSON.parse(event.data)
  console.log('initial configs', data)
})

es.addEventListener('update', event => {
  const data = JSON.parse(event.data)
  console.log('updated configs', data)
})

es.addEventListener('not-found', () => {
  console.log('author not found')
})

{
  "events": [
    "ready",
    "update",
    "not-found",
    "ping"
  ],
  "exampleReadyEvent": {
    "user": {
      "name": "Author Name",
      "avatar": "https://example.com/avatar.png",
      "tag": "1234",
      "provider": "discord",
      "createdAt": 123456789,
      "lastSeen": 123456789
    },
    "presenceConfigs": [],
    "statusConfigs": []
  }
}

/v1/authors/{authorId}/configsPOST

Auth required

Create presence or status config

Creates a new presence or status config for the given authorId (Discord snowflake) and links it under users/{authorId}/configs.

https://api.voidpresence.site/v1/authors/{authorId}/configs Copy URL

JSON responseHas example

fetch('https://api.voidpresence.site/v1/authors/123456789/configs', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    kind: 'presence',
    title: 'Presence title',
    author: 'Author name',
    description: 'Presence description',
    configData: {
      cycles: [{ details: 'Details line', state: 'State line' }],
      imageCycles: [
        {
          largeImage: 'https://example.com/large-image.png',
          largeText: 'Large image text',
          smallImage: 'https://example.com/small-image.png',
          smallText: 'Small image text'
        }
      ],
      buttonPairs: [
        {
          label1: 'Button 1 label',
          url1: 'https://example.com/button-1',
          label2: 'Button 2 label',
          url2: 'https://example.com/button-2'
        }
      ]
    },
    downloads: 0,
    uploadedAt: Date.now(),
    averageColor: '#ffffff'
  }),
})
  .then(res => res.json())
  .then(result => console.log(result.id))

{
  "requestBody": {
    "kind": "presence",
    "title": "Presence title",
    "author": "Author name",
    "description": "Presence description",
    "configData": {
      "cycles": [
        {
          "details": "Details line",
          "state": "State line"
        }
      ],
      "imageCycles": [
        {
          "largeImage": "https://example.com/large-image.png",
          "largeText": "Large image text",
          "smallImage": "https://example.com/small-image.png",
          "smallText": "Small image text"
        }
      ],
      "buttonPairs": [
        {
          "label1": "Button 1 label",
          "url1": "https://example.com/button-1",
          "label2": "Button 2 label",
          "url2": "https://example.com/button-2"
        }
      ]
    },
    "downloads": 0,
    "uploadedAt": 123456789,
    "averageColor": "#ffffff"
  },
  "responseBody": {
    "id": "123456789"
  }
}

/v1/authors/{authorId}/configsGET

Public

Get author profile and configs

Returns author profile and all of their presence/status configs by authorId (Discord snowflake). Used by internal profile pages.

https://api.voidpresence.site/v1/authors/{authorId}/configs Copy URL

JSON responseHas example

fetch('https://api.voidpresence.site/v1/authors/123456789/configs')
  .then(res => res.json())
  .then(data => console.log(data))

{
  "user": {
    "id": "123456789",
    "name": "Author Name",
    "avatar": "https://example.com/avatar.png",
    "tag": "1234",
    "provider": "discord",
    "createdAt": 123456789,
    "lastSeen": 123456789
  },
  "presenceConfigs": [],
  "statusConfigs": []
}

/v1/authors/{authorId}/streamGET
Public
Stream author profile and configs
Streams live updates for an author profile and their configs via Server-Sent Events. Events: ready, update, ping.
https://api.voidpresence.site/v1/authors/{authorId}/stream Copy URL
JSON response

/api/v1/configsPOST

Public

List all configs once

Returns a snapshot list of all presence or status configs. Body: { kind: "presence" | "status" }.

https://voidpresence.site/api/v1/configs Copy URL

JSON responseHas example

fetch('https://voidpresence.site/api/v1/configs', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ kind: 'presence' }),
})
  .then(res => res.json())
  .then(list => console.log(list))

[
  {
    "id": "123456789",
    "title": "Config title",
    "author": "Author name",
    "authorAvatar": "https://example.com/avatar.png",
    "authorTag": "1234",
    "downloads": 0,
    "description": "Config description",
    "averageColor": "#ffffff",
    "configData": {},
    "uploadedAt": 123456789
  }
]

/api/v1/configs/streamGET
Public
Stream all configs
Streams a live list of all configs via SSE. Query: kind=presence|status. Events: ready, update, ping.
https://voidpresence.site/api/v1/configs/stream Copy URL
JSON response

/v1/configs/{id}POST

Public

Get presence or status config

Returns a single presence or status config by ID, enriched with author metadata. Body: { kind: "presence" | "status" }.

https://api.voidpresence.site/v1/configs/{id} Copy URL

JSON responseHas example

fetch('https://api.voidpresence.site/v1/configs/123456789', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ kind: 'presence' }),
})
  .then(res => res.json())
  .then(config => console.log(config))

{
  "requestBody": {
    "kind": "presence"
  },
  "responseBody": {
    "id": "123456789",
    "title": "Config title",
    "author": "Author name",
    "authorAvatar": "https://example.com/avatar.png",
    "authorTag": "1234",
    "downloads": 0,
    "description": "Config description",
    "configData": {},
    "averageColor": "#ffffff",
    "uploadedAt": 123456789
  }
}

/api/v1/configs/{id}/streamGET
Public
Stream config by id
Streams live updates for a single presence or status config via SSE. Query: kind=presence|status. Events: ready, update, not-found, ping.
https://voidpresence.site/api/v1/configs/{id}/stream Copy URL
JSON response

/api/v1/configs/{id}/downloadGET

Public

Download config JSON file

Downloads only the configData of a presence or status config as a JSON file. Query: kind=presence|status.

https://voidpresence.site/api/v1/configs/{id}/download Copy URL

JSON responseHas example

fetch('https://voidpresence.site/api/v1/configs/123456789/download?kind=presence')
  .then(res => res.blob())
  .then(file => console.log(file))

{
  "status": "200 OK",
  "headers": {
    "Content-Type": "application/json",
    "Content-Disposition": "attachment; filename=\"config.json\""
  }
}

/api/v1/configs/{id}/copyGET
Public
Copy config JSON
Returns only the configData JSON for a presence or status config, suitable for copying or exporting. Query: kind=presence|status.
https://voidpresence.site/api/v1/configs/{id}/copy Copy URL
JSON responseHas example
fetch('https://voidpresence.site/api/v1/configs/123456789/copy?kind=presence') .then(res => res.json()) .then(json => console.log(json))
{ "cycles": [], "imageCycles": [], "buttonPairs": [] }
/api/v1/configs/{id}/deleteDELETE
Auth required
Delete presence or status config
Deletes a presence or status config and unlinks it from its owner. Query: kind=presence|status.
https://voidpresence.site/api/v1/configs/{id}/delete Copy URL
JSON responseHas example
fetch('https://voidpresence.site/api/v1/configs/123456789/delete?kind=presence', { method: 'DELETE', }) .then(res => res.json()) .then(result => console.log(result))
{ "ok": true, "ownerId": "123456789" }

/v1/github/releasesPOST

Public

Get latest GitHub release

Returns latest release info from GitHub for the selected Void Presence app (application, installer or updates).

https://api.voidpresence.site/v1/github/releases Copy URL

JSON responseHas example

fetch('https://api.voidpresence.site/v1/github/releases', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ app: 'void-presence' }),
})
  .then(res => res.json())
  .then(info => console.log(info))

{
  "requestBody": {
    "app": "void-presence"
  },
  "responseBody": {
    "tag": "vX.Y.Z",
    "assetName": "Void.Presence.Setup.X.Y.Z.exe",
    "downloadUrl": "https://github.com/Devollox/void-presence/releases/download/vX.Y.Z/Void.Presence.Setup.X.Y.Z.exe",
    "body": "vX.Y.Z release notes body text here."
  }
}

/v1/users/{id}GET

Public

Get user profile

Returns user profile data without configs, looked up by user id.

https://api.voidpresence.site/v1/users/{id} Copy URL

JSON responseHas example

fetch('https://api.voidpresence.site/v1/users/123456789')
  .then(res => res.json())
  .then(user => console.log(user))

{
  "id": "123456789",
  "name": "User Name",
  "avatar": "https://example.com/avatar.png",
  "tag": "1234",
  "provider": "discord"
}

/v1/analytics/appPOST

Auth required

Track app analytics

Tracks global app analytics such as total visitors and installer downloads.

https://api.voidpresence.site/v1/analytics/app Copy URL

JSON responseHas example

fetch('https://api.voidpresence.site/v1/analytics/app', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'app_download',
    channel: 'installer',
  }),
})
  .then(res => res.json())
  .then(result => console.log(result))

{
  "requestBody": {
    "type": "app_download",
    "channel": "installer",
    "meta": {
      "platform": "windows",
      "version": "2.5.0"
    }
  },
  "responseBody": {
    "ok": true,
    "type": "app_download",
    "stats": {
      "downloads": {
        "count": 123,
        "lastUpdated": 123456789
      }
    }
  }
}

/v1/analytics/configsPOST

Public

Track config analytics

Records analytics events for presence/status configs. Supported types: "status_download", "presence_download".

https://api.voidpresence.site/v1/analytics/configs Copy URL

JSON responseHas example

fetch('https://api.voidpresence.site/v1/analytics/configs', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ type: 'presence_download', id: '123456789' }),
})
  .then(res => res.json())
  .then(result => console.log(result))

{
  "requestBody": {
    "type": "presence_download",
    "id": "123456789",
    "client": "void-desktop",
    "meta": {
      "platform": "windows",
      "version": "2.5.0"
    }
  },
  "responseBody": {
    "ok": true
  }
}

/api/v1/analytics/streamGET
Public
Stream analytics stats
Streams live analytics stats via SSE. Events: ready, update, ping.
https://voidpresence.site/api/v1/analytics/stream Copy URL
JSON response

/api/auth/sessionGET

Auth required

Get current session

Returns the current next-auth session including provider details and tokens.

https://voidpresence.site/api/auth/session Copy URL

JSON responseHas example

fetch('https://voidpresence.site/api/auth/session')
  .then(res => res.json())
  .then(session => console.log(session))

{
  "user": {
    "name": "User name",
    "email": "user@example.com",
    "image": "https://example.com/avatar.png"
  },
  "expires": "2026-07-01T21:59:00.000Z",
  "provider": "discord",
  "accessToken": "access-token",
  "firebaseToken": "firebase-custom-token"
}

/api/auth/signin/{provider}GET
Public
Start OAuth sign-in
Starts OAuth sign-in for the given provider and redirects to the provider authorization page.
https://voidpresence.site/api/auth/signin/{provider} Copy URL
JSON response
window.location.href = 'https://voidpresence.site/api/auth/signin/discord'
{ "redirect": true, "provider": "discord", "url": "https://discord.com/oauth2/authorize?..." }
/api/auth/callback/{provider}GET
Public
Handle OAuth callback
Route used by next-auth to handle OAuth callbacks for configured providers.
https://voidpresence.site/api/auth/callback/{provider} Copy URL
JSON response
fetch('https://voidpresence.site/api/auth/callback/discord') .then(res => res.json()) .then(result => console.log(result))
{ "ok": true, "provider": "discord" }

/api/auth/fuckoffnextauth/{provider}GET

Public

Steam OAuth bridge

Custom bridge route used by the Steam provider to normalize callback parameters before passing them to next-auth.

https://voidpresence.site/api/auth/fuckoffnextauth/{provider} Copy URL

JSON responseHas example

fetch('https://voidpresence.site/api/auth/fuckoffnextauth/steam?state=state-value&code=authorization-code&redirectUri=https://example.com/callback')
  .then(res => res.json())
  .then(result => console.log(result.normalizedParams))

{
  "ok": true,
  "provider": "steam",
  "normalizedParams": {
    "state": "state-value",
    "code": "authorization-code",
    "redirectUri": "https://example.com/callback"
  }
}

All endpoints respond with JSON and follow the same structure as your presence and status configs.