REST API

API Documentation

Push updates to your topics programmatically using our REST API. Integrate BEEPRLY into your workflows with ease.

Getting Started

The BEEPRLY API allows you to programmatically create updates for your topics. This is perfect for integrating external services, automation, or building custom integrations.

Base URL

https://beeprly.com

Authentication

All API requests require authentication using an API key. You can generate an API key for your topic in the BEEPRLY mobile app.

How to Get Your API Key

  1. Open the BEEPRLY mobile app
  2. Navigate to your topic
  3. Enable API access for the topic
  4. Copy your generated API key

Using Your API Key

Include your API key in the request header using one of these methods:

Method 1: X-API-Key Header

X-API-Key: your-api-key-here

Method 2: Authorization Bearer

Authorization: Bearer your-api-key-here

Create Update

POST/api/updates

Creates a new update for a topic. The update will appear in the topic's feed and notify all subscribers.

Request Body

Required Fields

topicId

(string) - The ID of the topic to post the update to

type

(string) - The type of update: text, photo, link, location, or mixed

Optional Fields

text

(string) - Text content for the update (required for text and mixed types)

photoUrl

(string) - URL to an image (required for photo type)

link

(string) - A valid HTTP/HTTPS URL (required for link type)

location

(object) - Location data with lat, lng, and optional label (required for location type)

Update Types

📝text

A text-only update. Requires the text field.

📷photo

An update with an image. Requires the photoUrl field.

🔗link

An update with a link. Requires the link field (must be a valid HTTP/HTTPS URL).

📍location

An update with location data. Requires the location object with lat and lng.

🔀mixed

An update that can combine text, photo, and/or link. Requires at least one of: text, photoUrl, or link.

Examples

1Example 1: Text Update

curl -X POST https://beeprly.com/api/updates \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "topicId": "abc123",
    "type": "text",
    "text": "Hello from the API! This is a text update."
  }'

2Example 2: Photo Update

curl -X POST https://beeprly.com/api/updates \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "topicId": "abc123",
    "type": "photo",
    "photoUrl": "https://example.com/image.jpg"
  }'

3Example 3: Link Update

curl -X POST https://beeprly.com/api/updates \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "topicId": "abc123",
    "type": "link",
    "link": "https://example.com/article"
  }'

4Example 4: Location Update

curl -X POST https://beeprly.com/api/updates \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "topicId": "abc123",
    "type": "location",
    "location": {
      "lat": 40.7128,
      "lng": -74.0060,
      "label": "New York City"
    }
  }'

5Example 5: Mixed Update

curl -X POST https://beeprly.com/api/updates \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "topicId": "abc123",
    "type": "mixed",
    "text": "Check out this article!",
    "link": "https://example.com/article",
    "photoUrl": "https://example.com/image.jpg"
  }'

Response

201 Created

Success Response

{
  "success": true,
  "updateId": "update-document-id",
  "update": {
    "id": "update-document-id",
    "topicId": "abc123",
    "authorId": "api",
    "type": "text",
    "text": "Hello from the API!",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Error Responses

401

Unauthorized - Missing or invalid API key

{
  "error": "Invalid API key"
}
400

Bad Request - Invalid request body

{
  "error": "text is required for type \"text\""
}
403

Forbidden - API key scoped to different topic

{
  "error": "API key is scoped to a different topic"
}
404

Not Found - Topic doesn't exist

{
  "error": "Topic not found"
}
429

Too Many Requests - Rate limit exceeded

{
  "error": "Rate limit exceeded. Please wait 5 seconds before making another request.",
  "retryAfter": 5
}

Rate Limiting

To ensure fair usage and prevent abuse, the API enforces rate limiting. Each API key is limited to:

1
Request
/
10
Seconds

Rate limits are enforced per API key. If you exceed the limit, you'll receive a 429 status code with a Retry-After header indicating when you can make your next request.

Rate Limit Response (429 Too Many Requests)

{
  "error": "Rate limit exceeded. Please wait 5 seconds before making another request.",
  "retryAfter": 5
}

Response headers include: Retry-After, X-RateLimit-Limit, and X-RateLimit-Window

Best Practices

  • Keep your API key secure and never commit it to version control
  • Use environment variables to store your API key
  • Respect rate limits and implement exponential backoff when you receive 429 responses
  • Validate your request data before sending to avoid unnecessary errors
  • Handle errors gracefully and implement retry logic for transient failures
  • API keys are scoped to specific topics - ensure you're using the correct key for each topic
  • Updates created via API will have authorId: "api" to distinguish them from user-created updates