Introduction

Limiter's HTTP API is organized around action-centric URLs. All methods are in the form of POST requests with the URL path denoting the type of action and the relevant data sent in the request body.

We also have language bindings in Go, Python, and TypeScript. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

The Limiter API uses tokens to authenticate requests.

Limiter provides two types of API tokens, account-level token and project-level token. The account-level token can be obtained from your Account settings, while project-level tokens can be obtained from the respective project's Plan / Feature code examples.

The API token should be included in all API requests to the server.

Core API

Get Feature Matrix

import "github.com/microrg/go-limiter/limiter"

client := limiter.New("project_id").WithDefaultBackend("api_token")

featureMatrix := client.FeatureMatrix()

from pylimiter import limiter

client = limiter.Client('project_id', {
  'backend': 'Default',
  'api_token': 'api_token',
})

feature_matrix = client.feature_matrix()

curl --location --request POST 'https://www.applimiter.com/api/v1/feature-matrix' \
--header 'Authorization: api_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "project_id": "project_id"
}'

import { Limiter } from 'ts-limiter';

const client = new Limiter('project_id', {
  backend: 'Default',
  apiToken: 'api_token',
});

const featureMatrix = await client.featureMatrix();

Response

{
    "plans": [
        {
            "plan_id": "Hobby",
            "features": [
                {
                    "soft": false,
                    "type": "Boolean",
                    "value": 1,
                    "enabled": true,
                    "webhook": {},
                    "metadata": {},
                    "feature_id": "BasicLimits"
                }
            ]
        }
    ]
}

Retrieve the feature matrix for a project.

HTTP Request

POST https://www.applimiter.com/api/v1/feature-matrix

Query Parameters

Parameter	Description
project_id (string)	The ID of the project.

Get Usage

import "github.com/microrg/go-limiter/limiter"

client := limiter.New("project_id").WithDefaultBackend("api_token")

usage := client.Usage("user_id")

from pylimiter import limiter

client = limiter.Client('project_id', {
  'backend': 'Default',
  'api_token': 'api_token',
})

usage = client.usage('user_id')

curl --location --request POST 'https://www.applimiter.com/api/v1/usage' \
--header 'Authorization: api_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "user_id",
    "project_id": "project_id"
}'

import { Limiter } from 'ts-limiter';

const client = new Limiter('project_id', {
  backend: 'Default',
  apiToken: 'api_token',
});

const usage = await client.usage('user_id');

Response

{
    "usage": {
        "AdminEmails": 3,
        "SyncInsights": 0
    },
    "plan_id": "Team",
    "user_id": "0f023fe5-f361-4c40-bded-cca4f44662c3"
}

Retrieve the user's feature usage stats.

HTTP Request

POST https://www.applimiter.com/api/v1/usage

Body Parameters

Parameter	Description
user_id (string)	The ID of the user.
project_id (string)	The ID of the project.

Bind User

import "github.com/microrg/go-limiter/limiter"

client := limiter.New("project_id").WithDefaultBackend("api_token")

client.Bind("plan_name", "user_id")

client = limiter.Client('project_id', {
  'backend': 'Default',
  'api_token': 'api_token',
})

client.bind('plan_name', 'user_id')

curl --location --request POST 'https://www.applimiter.com/api/v1/bind' \
--header 'Authorization: api_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "user_id",
    "project_id": "project_id",
    "plan_id": "plan_name"
}'

import { Limiter } from 'ts-limiter';

const client = new Limiter('project_id', {
  backend: 'Default',
  apiToken: 'api_token',
});

await client.bind('plan_name', 'user_id');

Response

{}

Bind a user to a plan.

HTTP Request

POST https://www.applimiter.com/api/v1/bind

Body Parameters

Parameter	Description
user_id (string)	The ID of the user.
project_id (string)	The ID of the project.
plan_id (string)	The name of the plan.

Evaluate Feature Flag

import "github.com/microrg/go-limiter/limiter"

client := limiter.New("project_id").WithDefaultBackend("api_token")

if client.Feature("feature_name", "user_id") {
    // Allow
}

client = limiter.Client('project_id', {
  'backend': 'Default',
  'api_token': 'api_token',
})

if client.feature('feature_name', 'user_id'):
  print('Allow')

curl --location --request POST 'https://www.applimiter.com/api/v1/feature' \
--header 'Authorization: api_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "user_id",
    "project_id": "project_id",
    "feature_id": "feature_name"
}'

import { Limiter } from 'ts-limiter';

const client = new Limiter('project_id', {
  backend: 'Default',
  apiToken: 'api_token',
});

if (await client.feature('feature_name', 'user_id')) {
  // Allow
}

Response

{
    "plan": "Team",
    "allow": false,
    "metadata": {
        "test": 2
    },
    "reason": "Exceeded usage limits on feature"
}

Check that the user is entitled to the feature and has not exceeded their usage limits.

The SDKs only return a boolean response. The HTTP API returns a much richer json response. The metadata field contains arbitrary json metadata that has been attached to the feature flag.

HTTP Request

POST https://www.applimiter.com/api/v1/feature

Body Parameters

Parameter	Description
user_id (string)	The ID of the user.
project_id (string)	The ID of the project.
feature_id (string)	The name of the feature.

Increment Usage

import "github.com/microrg/go-limiter/limiter"

client := limiter.New("project_id").WithDefaultBackend("api_token")

client.Increment("feature_name", "user_id", 1)

client = limiter.Client('project_id', {
  'backend': 'Default',
  'api_token': 'api_token',
})

client.increment('feature_name', 'user_id', 1)

curl --location --request POST 'https://www.applimiter.com/api/v1/increment' \
--header 'Authorization: api_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "user_id",
    "project_id": "project_id",
    "feature_id": "feature_name",
    "value": value
}'

import { Limiter } from 'ts-limiter';

const client = new Limiter('project_id', {
  backend: 'Default',
  apiToken: 'api_token',
});

await client.increment('feature_name', 'user_id', 1);

Response

{}

Increment the user's usage of a feature by a specified amount.

HTTP Request

POST https://www.applimiter.com/api/v1/increment

Body Parameters

Parameter	Default	Description
user_id (string)		The ID of the user.
project_id (string)		The ID of the project.
feature_id (string)		The name of the feature.
value (number)	1	Optional. The value to increment usage by.

Decrement Usage

import "github.com/microrg/go-limiter/limiter"

client := limiter.New("project_id").WithDefaultBackend("api_token")

client.Decrement("feature_name", "user_id", 1)

client = limiter.Client('project_id', {
  'backend': 'Default',
  'api_token': 'api_token',
})

client.decrement('feature_name', 'user_id', 1)

curl --location --request POST 'https://www.applimiter.com/api/v1/decrement' \
--header 'Authorization: api_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "user_id",
    "project_id": "project_id",
    "feature_id": "feature_name",
    "value": value
}'

import { Limiter } from 'ts-limiter';

const client = new Limiter('project_id', {
  backend: 'Default',
  apiToken: 'api_token',
});

await client.decrement('feature_name', 'user_id', 1);

Response

{}

Decrement the user's usage of a feature by a specified amount.

HTTP Request

POST https://www.applimiter.com/api/v1/decrement

Body Parameters

Parameter	Default	Description
user_id (string)		The ID of the user.
project_id (string)		The ID of the project.
feature_id (string)		The name of the feature.
value (number)	1	Optional. The value to decrement usage by.

Set Usage

import "github.com/microrg/go-limiter/limiter"

client := limiter.New("project_id").WithDefaultBackend("api_token")

client.Set("feature_name", "user_id", value)

client = limiter.Client('project_id', {
  'backend': 'Default',
  'api_token': 'api_token',
})

client.set('feature_name', 'user_id', value)

curl --location --request POST 'https://www.applimiter.com/api/v1/set' \
--header 'Authorization: api_token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_id": "user_id",
    "project_id": "project_id",
    "feature_id": "feature_name",
    "value": value
}'

import { Limiter } from 'ts-limiter';

const client = new Limiter('project_id', {
  backend: 'Default',
  apiToken: 'api_token',
});

await client.set('feature_name', 'user_id', value);

Response

{}

Set the user's usage of a feature to a specified value.

HTTP Request

POST https://www.applimiter.com/api/v1/set

Body Parameters

Parameter	Description
user_id (string)	The ID of the user.
project_id (string)	The ID of the project.
feature_id (string)	The name of the feature.
value (number)	The value to set usage to.

Errors

The Limiter HTTP API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- You are unable to access the specified resource.
404	Not Found -- The specified resource could not be found.
429	Too Many Requests -- Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.