Rest API

All endpoints are available on https://api.freestuffbot.xyz/v2

Auth

You should already have an API key. If not please check out the Getting Started page.

Your API key should be present in the Authorization header on every request to the API. Prefix your API key with the word Bearer.

Assuming your API key is "ABCDEFGHIJKLMNOPQRSTUVWXYZ", this is how your header should look like:
Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ

List of endpoints

Endpoints are grouped into "Static" and "Content". If you are on the free tier you only have access to endpoints in the "static" group. Upgrade to get access to content endpoints.

Static

All schemas returned by endpoints in this category are defined following the https://json-schema.org/ specification.
GEThttps://api.freestuffbot.xyz/v2/ping

Parameters

LocationKeyTypeDescriptionheaderAuthorizationstringYour Bearer token

Responses

204
No Content
SuccessBody(none)Headers
(none)
GEThttps://api.freestuffbot.xyz/v2/static/schemas

Parameters

LocationKeyTypeDescriptionheaderAuthorizationstringYour Bearer token

Responses

200
OK
SuccessBody{ "type": "fsb:static:apiv2:schema_list", "list": [ { "name": "Product", "urn": "fsb:schema:apiv2:product", "active": true, "latestVersion": "9999-99-99" } ] }Headers
(none)
GEThttps://api.freestuffbot.xyz/v2/static/schemas/:urn

Parameters

LocationKeyTypeDescriptionheaderAuthorizationstringYour Bearer token

Responses

200
OK
SuccessBody{ "type": "fsb:static:apiv2:schema", "schema": { "type": "object", "properties": {} } }Headers
(none)
404
Not Found
No schema with the given URN was found.Body{ "type": "fsb:problem:name-here", "title": "error name", "detail": "error message" }Headers
(none)
GEThttps://api.freestuffbot.xyz/v2/static/problems

Parameters

LocationKeyTypeDescriptionheaderAuthorizationstringYour Bearer token

Responses

200
OK
SuccessBody{ "type": "fsb:static:apiv2:problem_list", "list": [ { "urn": "fsb:problem:example", "status": 400, "title": "Example error" } ] }Headers
(none)
GEThttps://api.freestuffbot.xyz/v2/static/events

Parameters

LocationKeyTypeDescriptionheaderAuthorizationstringYour Bearer token

Responses

200
OK
SuccessBody{ "type": "fsb:static:apiv2:event_list", "list": [ { "urn": "fsb:event:example", "description": "Human readable description of the event", "payloadDescription": "Human readable description of the event payload", "payloadSchema": { "type": "object", "properties": {} } } ] }Headers
(none)

Content

The endpoints in this category are only available to users in the "full" tier or above.
GEThttps://api.freestuffbot.xyz/v2/products

Parameters

LocationKeyTypeDescriptionheaderAuthorizationstringYour Bearer tokenheaderIf-None-Match?stringA previously received ETag value. Recommended but not required.querylimit?intLimit how many products are returned at oncequeryoffset?intOffset the results. Used with limit parameter for pagination.queryresolve?booleanIf set to true will return full products instead of partial ones. The ETag hash will also be computed over the entire product data and not just their ids.querytype?ChannelFilter: Only list products with the given typequerykind?ProductKindFilter: Only list products with the given kindquerystore?ProductStoreFilter: Only list products with the given store

Responses

200
OK
Success. Returns a list of PartialProduct objects and a number of total results. Even if no "limit" parameter is provided the results might be limited to a certain page size. Use the total count to determine if a second request is required.Body{ "products": [ { "id": 123456, "kind": "game", "until": 0, "type": "keep", "flags": 0, "store": "steam" } ], "count": 1 }Headers
ETag=<hash:string>— see developer.mozilla.org/docs/Web/HTTP/Headers/ETag - will be a weak hash if resolve is false, strong hash if resolve is true. The hash will always include all products valid for your query, even if cut off through pagination. In other words, you will receive the same hash for different "offset" and "limit" values.
304
Not Modified
No changes since last request.BodynullHeaders
(none)
400
Bad Request
Invalid product id.Body{ "type": "fsb:problem:name-here", "title": "error name", "detail": "error message" }Headers
(none)
404
Not Found
No product with your id was found.Body{ "type": "fsb:problem:name-here", "title": "error name", "detail": "error message" }Headers
(none)
GEThttps://api.freestuffbot.xyz/v2/products/:id

Parameters

LocationKeyTypeDescriptionroute:idstringThe id of the product you're looking upheaderAuthorizationstringYour Bearer tokenheaderIf-None-Match?stringA previously received ETag value. Recommended but not required.

Responses

200
OK
SuccessBody{ "TODO": true }Headers
ETag=<hash:string>— see developer.mozilla.org/docs/Web/HTTP/Headers/ETag
304
Not Modified
No changes since last request.BodynullHeaders
(none)
400
Bad Request
Invalid product id.Body{ "type": "fsb:problem:name-here", "title": "error name", "detail": "error message" }Headers
(none)
404
Not Found
No product with your id was found.Body{ "type": "fsb:problem:name-here", "title": "error name", "detail": "error message" }Headers
(none)
502
Bad Gateway
An internal error, try again after a few seconds.Body{ "type": "fsb:problem:name-here", "title": "error name", "detail": "error message" }Headers
(none)
Edit this page on GitHub
Table of Contents