Skip to main content

API Overview

The tagd-ai API allows you to programmatically manage tags, files, and webhooks. Build integrations, automate workflows, and extend tagd-ai's functionality.

Getting Started​

Prerequisites​

To use the API, you need:

  • A tagd-ai account
  • Pro or Enterprise subscription
  • An API key

Base URL​

All API requests go to:

https://api.tagd-ai.com/v1

Quick Example​

Create a tag with a simple API call:

curl -X POST https://api.tagd-ai.com/v1/tags \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First API Tag",
    "content": [
      {
        "type": "text",
        "content": "Created via API!"
      }
    ]
  }'

API Features​

Tag Management​

  • Create, read, update, delete tags
  • Manage tag content and blocks
  • Set permissions and settings
  • Generate and retrieve QR codes

File Operations​

  • Upload files to tags
  • Download file content
  • Manage file attachments
  • Handle images and documents

Webhook Management​

  • Create and configure webhooks
  • List active webhooks
  • View webhook delivery history
  • Test webhook endpoints

Analytics Access​

  • Retrieve tag view statistics
  • Access access logs
  • Export analytics data

Response Format​

All responses are JSON:

Success Response​

{
  "success": true,
  "data": {
    "id": "abc123",
    "title": "My Tag",
    ...
  }
}

Error Response​

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Title is required"
  }
}

HTTP Methods​

MethodUse
GETRetrieve resources
POSTCreate resources
PUTUpdate resources (full replace)
PATCHUpdate resources (partial)
DELETERemove resources

Status Codes​

CodeMeaning
200Success
201Created
204No content (success)
400Bad request
401Unauthorized
403Forbidden
404Not found
429Rate limited
500Server error

Rate Limiting​

Requests are rate limited per plan:

PlanPer MinutePer Day
Pro6010,000
Enterprise300100,000

Rate limit headers included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

Pagination​

List endpoints support pagination:

Request​

GET /v1/tags?limit=20&offset=0

Parameters​

ParameterDescriptionDefault
limitItems per page (max 100)20
offsetSkip this many items0

Response​

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Versioning​

The API is versioned via the URL path:

  • Current version: /v1
  • Version included in all endpoints

Breaking changes result in new version. We maintain backward compatibility within versions.

SDKs and Libraries​

Official SDKs​

Coming soon:

  • JavaScript/TypeScript
  • Python
  • Go

Community Libraries​

Check our GitHub for community contributions.

Testing​

Sandbox Environment​

Test API in sandbox mode:

  • Base URL: https://sandbox.api.tagd-ai.com/v1
  • Use test API keys
  • No charges incurred
  • Data periodically cleared

Test API Keys​

Generate test keys:

  1. Go to Account → API Keys
  2. Click Create Test Key
  3. Use for development/testing

API Changelog​

Stay updated on API changes:

  • Subscribe to API changelog
  • Review breaking changes before versions
  • See API Status for uptime

Support​

Resources​

Reporting Issues​

Include in bug reports:

  • Request ID (in response headers)
  • Endpoint called
  • Request body (redact secrets)
  • Response received
  • Expected behavior

Next Steps​