bah.is API Documentation

System

Health and status

GET /health Health check No auth required

Responses

200 Service is healthy

{
  "status": "ok",
  "service": "api.bah.is"
}

Code Examples

curl -X GET "https://api.bah.is/health" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/health', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/health',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

Links

Create, read, update, delete short links

GET /v1/links List links Auth required

Parameters

Name	In	Type	Required
`page`	query	integer	optional
`limit`	query	integer	optional
`search`	query	string	optional

Responses

200 List of links with pagination

401 Authentication required

Code Examples

curl -X GET "https://api.bah.is/v1/links" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/links', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/links',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

POST /v1/links Create a short link No auth required

Request Body

Field	Type	Required	Description
`url`	string	required	Destination URL
`slug`	string	optional	Custom slug (optional)
`title`	string	optional	Link title (optional)
`domain`	string	optional	Custom domain (optional, Pro only)

{
  "url": "https://example.com/my-page",
  "slug": "my-link",
  "title": "My Link",
  "domain": "links.myco.com"
}

Responses

201 Link created

{
  "data": {
    "id": "abc123",
    "slug": "my-link",
    "shortUrl": "https://bah.is/my-link",
    "destination": "https://example.com/my-page",
    "title": "My Link"
  },
  "error": null,
  "meta": null
}

400 Invalid URL or slug

409 Slug already taken

429 Rate limit exceeded

Code Examples

curl -X POST "https://api.bah.is/v1/links" \
  \
  -H "Authorization: Bearer bah_your_api_key"  \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/my-page",
  "slug": "my-link",
  "title": "My Link",
  "domain": "links.myco.com"
}'

const res = await fetch('https://api.bah.is/v1/links', {
  method: 'POST',
    headers: { 'Authorization': 'Bearer bah_your_api_key', 'Content-Type': 'application/json' },
    body: JSON.stringify({
  "url": "https://example.com/my-page",
  "slug": "my-link",
  "title": "My Link",
  "domain": "links.myco.com"
})
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
  'https://api.bah.is/v1/links',
  headers={'Authorization': 'Bearer bah_your_api_key'},
json={
  'url': 'https://example.com/my-page',
  'slug': 'my-link',
  'title': 'My Link',
  'domain': 'links.myco.com'
},
)
print(res.json())

GET /v1/links/{id} Get link details Auth required

Parameters

Name	In	Type	Required	Description
`id`	path	string	required

Responses

200 Link details

404 Link not found

Code Examples

curl -X GET "https://api.bah.is/v1/links/{id}" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/links/{id}', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/links/{id}',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

PUT /v1/links/{id} Update a link Auth required

Parameters

Name	In	Type	Required	Description
`id`	path	string	required

Request Body

Field	Type	Required
`url`	string	optional
`slug`	string	optional
`title`	string	optional

{
  "url": "example_url",
  "slug": "example_slug",
  "title": "example_title"
}

Responses

200 Link updated

404 Link not found

Code Examples

curl -X PUT "https://api.bah.is/v1/links/{id}" \
  \
  -H "Authorization: Bearer bah_your_api_key"  \
  -H "Content-Type: application/json" \
  -d '{
  "url": "example_url",
  "slug": "example_slug",
  "title": "example_title"
}'

const res = await fetch('https://api.bah.is/v1/links/{id}', {
  method: 'PUT',
    headers: { 'Authorization': 'Bearer bah_your_api_key', 'Content-Type': 'application/json' },
    body: JSON.stringify({
  "url": "example_url",
  "slug": "example_slug",
  "title": "example_title"
})
});
const data = await res.json();
console.log(data);

import requests

res = requests.put(
  'https://api.bah.is/v1/links/{id}',
  headers={'Authorization': 'Bearer bah_your_api_key'},
json={
  'url': 'example_url',
  'slug': 'example_slug',
  'title': 'example_title'
},
)
print(res.json())

DELETE /v1/links/{id} Delete a link Auth required

Parameters

Name	In	Type	Required	Description
`id`	path	string	required

Responses

200 Link deleted

404 Link not found

Code Examples

curl -X DELETE "https://api.bah.is/v1/links/{id}" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/links/{id}', {
  method: 'DELETE',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.delete(
  'https://api.bah.is/v1/links/{id}',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

GET /v1/links/{id}/qr Get QR code for a link Auth required

Parameters

Name	In	Type	Required	Description
`id`	path	string	required

Responses

200 QR code SVG

Code Examples

curl -X GET "https://api.bah.is/v1/links/{id}/qr" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/links/{id}/qr', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/links/{id}/qr',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

User

User profile and consent management

GET /v1/me Get current user profile Auth required

Responses

200 User profile

{
  "data": {
    "id": "abc",
    "email": "user@example.com",
    "name": "John",
    "plan": "pro"
  }
}

Code Examples

curl -X GET "https://api.bah.is/v1/me" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/me', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/me',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

PATCH /v1/me/consents Update marketing consent Auth required

Request Body

Field	Type	Required	Description
`marketing`	boolean	optional

{
  "marketing": true
}

Responses

200 Consent updated

Code Examples

curl -X PATCH "https://api.bah.is/v1/me/consents" \
  \
  -H "Authorization: Bearer bah_your_api_key"  \
  -H "Content-Type: application/json" \
  -d '{
  "marketing": true
}'

const res = await fetch('https://api.bah.is/v1/me/consents', {
  method: 'PATCH',
    headers: { 'Authorization': 'Bearer bah_your_api_key', 'Content-Type': 'application/json' },
    body: JSON.stringify({
  "marketing": true
})
});
const data = await res.json();
console.log(data);

import requests

res = requests.patch(
  'https://api.bah.is/v1/me/consents',
  headers={'Authorization': 'Bearer bah_your_api_key'},
json={
  'marketing': true
},
)
print(res.json())

Analytics

Click analytics, real-time feed, export

GET /v1/analytics/overview Get analytics overview Auth required

Parameters

Name	In	Type	Required
`period`	query	string (24h, 7d, 30d, 90d, 1y, all)	optional
`compare`	query	boolean	optional
`linkId`	query	string	optional

Responses

200 Analytics data (locked for Free plan)

Code Examples

curl -X GET "https://api.bah.is/v1/analytics/overview" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/analytics/overview', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/analytics/overview',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

GET /v1/analytics/realtime Get real-time click feed Auth required

Last 20 clicks in real-time. Pro plan only.

Responses

200 Real-time click events

Code Examples

curl -X GET "https://api.bah.is/v1/analytics/realtime" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/analytics/realtime', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/analytics/realtime',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

GET /v1/analytics/link/{id} Get analytics for a specific link Auth required

Parameters

Name	In	Type	Required	Description
`id`	path	string	required
`period`	query	string	optional

Responses

200 Link-specific analytics

Code Examples

curl -X GET "https://api.bah.is/v1/analytics/link/{id}" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/analytics/link/{id}', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/analytics/link/{id}',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

GET /v1/analytics/export Export analytics data Auth required

Download analytics as CSV or JSON. Pro plan only.

Parameters

Name	In	Type	Required	Description
`format`	query	string (csv, json)	optional
`period`	query	string	optional

Responses

200 Downloaded file

Code Examples

curl -X GET "https://api.bah.is/v1/analytics/export" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/analytics/export', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/analytics/export',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

Domains

Custom domain management (Pro)

GET /v1/domains List custom domains Auth required

Pro plan only.

Responses

200 List of domains

Code Examples

curl -X GET "https://api.bah.is/v1/domains" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/domains', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/domains',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

POST /v1/domains Add a custom domain Auth required

Pro plan only. Limit: 1 domain.

Request Body

Field	Type	Required	Description
`domain`	string	required

{
  "domain": "links.myco.com"
}

Responses

201 Domain created with DNS instructions

403 Pro plan required

Code Examples

curl -X POST "https://api.bah.is/v1/domains" \
  \
  -H "Authorization: Bearer bah_your_api_key"  \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "links.myco.com"
}'

const res = await fetch('https://api.bah.is/v1/domains', {
  method: 'POST',
    headers: { 'Authorization': 'Bearer bah_your_api_key', 'Content-Type': 'application/json' },
    body: JSON.stringify({
  "domain": "links.myco.com"
})
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
  'https://api.bah.is/v1/domains',
  headers={'Authorization': 'Bearer bah_your_api_key'},
json={
  'domain': 'links.myco.com'
},
)
print(res.json())

GET /v1/domains/{id}/verify Check domain verification status Auth required

Parameters

Name	In	Type	Required	Description
`id`	path	string	required

Responses

200 Current status

Code Examples

curl -X GET "https://api.bah.is/v1/domains/{id}/verify" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/domains/{id}/verify', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/domains/{id}/verify',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

DELETE /v1/domains/{id} Delete a custom domain Auth required

Parameters

Name	In	Type	Required	Description
`id`	path	string	required

Responses

200 Domain deleted

Code Examples

curl -X DELETE "https://api.bah.is/v1/domains/{id}" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/domains/{id}', {
  method: 'DELETE',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.delete(
  'https://api.bah.is/v1/domains/{id}',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

Buckets

Link buckets — multiple links in one URL (Pro)

GET /v1/buckets List link buckets Auth required

Pro plan only.

Responses

200 List of buckets

Code Examples

curl -X GET "https://api.bah.is/v1/buckets" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/buckets', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/buckets',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

POST /v1/buckets Create a link bucket Auth required

Bundle up to 10 links under one short URL. Pro plan only.

Request Body

Field	Type	Required
`name`	string	required
`slug`	string	optional
`links`	array	required

{
  "name": "Resources",
  "slug": "resources",
  "links": []
}

Responses

201 Bucket created

Code Examples

curl -X POST "https://api.bah.is/v1/buckets" \
  \
  -H "Authorization: Bearer bah_your_api_key"  \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Resources",
  "slug": "resources",
  "links": []
}'

const res = await fetch('https://api.bah.is/v1/buckets', {
  method: 'POST',
    headers: { 'Authorization': 'Bearer bah_your_api_key', 'Content-Type': 'application/json' },
    body: JSON.stringify({
  "name": "Resources",
  "slug": "resources",
  "links": []
})
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
  'https://api.bah.is/v1/buckets',
  headers={'Authorization': 'Bearer bah_your_api_key'},
json={
  'name': 'Resources',
  'slug': 'resources',
  'links': []
},
)
print(res.json())

API Keys

Programmatic access keys (Enterprise)

GET /v1/keys List API keys Auth required

Enterprise plan only.

Responses

200 List of API keys (prefix only)

Code Examples

curl -X GET "https://api.bah.is/v1/keys" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/keys', {
  method: 'GET',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
  'https://api.bah.is/v1/keys',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

POST /v1/keys Create an API key Auth required

Enterprise plan only. Full key shown once.

Responses

201 API key created

Code Examples

curl -X POST "https://api.bah.is/v1/keys" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/keys', {
  method: 'POST',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
  'https://api.bah.is/v1/keys',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

DELETE /v1/keys/{id} Revoke an API key Auth required

Parameters

Name	In	Type	Required	Description
`id`	path	string	required

Responses

200 Key revoked

Code Examples

curl -X DELETE "https://api.bah.is/v1/keys/{id}" \
  \
  -H "Authorization: Bearer bah_your_api_key"

const res = await fetch('https://api.bah.is/v1/keys/{id}', {
  method: 'DELETE',
    headers: { 'Authorization': 'Bearer bah_your_api_key' }
});
const data = await res.json();
console.log(data);

import requests

res = requests.delete(
  'https://api.bah.is/v1/keys/{id}',
  headers={'Authorization': 'Bearer bah_your_api_key'},
)
print(res.json())

bah.is API

Authentication

Response Format

System

Responses

Code Examples

Links

Parameters

Responses

Code Examples

Request Body

Responses

Code Examples

Parameters

Responses

Code Examples

Parameters

Request Body

Responses

Code Examples

Parameters

Responses

Code Examples

Parameters

Responses

Code Examples

User

Responses

Code Examples

Request Body

Responses

Code Examples

Analytics

Parameters

Responses

Code Examples

Responses

Code Examples

Parameters

Responses

Code Examples

Parameters

Responses

Code Examples

Domains

Responses

Code Examples

Request Body

Responses

Code Examples

Parameters

Responses

Code Examples

Parameters

Responses

Code Examples

Buckets

Responses

Code Examples

Request Body

Responses

Code Examples

API Keys

Responses

Code Examples

Responses

Code Examples

Parameters

Responses

Code Examples