Introducing the Sejhey REST API

The Sejhey REST API provides programmatic access to all translation management features in your Sejhey projects. Built on standard REST principles, the API enables you to integrate translation workflows into your applications, automate localization processes, and build custom tools that interact with your translation data.

API Overview

The Sejhey API is a RESTful API that uses JSON for request and response payloads. All endpoints are versioned under /api/v1 and require authentication via API keys. The API provides comprehensive coverage of translation management operations, from basic CRUD operations on keys and translations to advanced features like task management, quality assurance, and release management.

Authentication

All API requests must include your API key in the X-API-Key header. API keys are project-specific and can be created in your project settings under the API Tokens section. Each API key can be configured with granular permissions, allowing you to control exactly what operations the key can perform.

The authentication scheme uses API key authentication:

• Header parameter name: X-API-Key
• Security scheme type: apiKey

Base URL

All API requests are made to:

https://app.sejhey.com/api/v1

Core Functionality

Keys and Translations

The API provides full control over translation keys and their values. You can create, read, update, and delete keys programmatically. Each key can have translations in multiple languages, with support for variations (region-specific translations) and namespaces for organizing keys into logical groups.

Key operations include:

• Listing all keys in a project with filtering options
• Creating individual keys or batch creating multiple keys at once
• Updating key metadata, default values, and descriptions
• Deleting keys and their associated translations
• Searching keys by name or other criteria

Translation operations allow you to:

• Retrieve translations for specific languages or all languages
• Update translation values directly
• Access translation history and change logs
• Review and approve translations programmatically

Language Management

Manage project languages through the API. Add new languages, configure language-specific settings, set default countries, and manage language variations. The API supports all standard locale codes and allows you to configure how translations are handled for each language.

Project Management

Access and modify project settings, metadata, and configuration through dedicated endpoints. This includes project name, default language, project settings, and other configuration options.

Tasks and Workflows

Create and manage translation tasks programmatically. Assign tasks to specific contributors, set deadlines, and track progress. Tasks can be associated with specific keys, languages, or both, providing flexible workflow management.

Screenshots

Upload screenshots and associate them with translation keys to provide visual context for translators. The API supports uploading screenshots via base64 encoding or file uploads, and allows you to set coordinates to highlight specific areas on screenshots.

Glossary Management

Maintain project glossaries through the API. Create glossary terms, define translations for different languages, and associate terms with specific keys. The glossary system helps ensure consistent terminology across translations.

Releases

Create and manage translation releases through the API. Releases allow you to bundle specific translations for deployment, supporting staging and production environments. You can create releases, add or remove keys from releases, and download release packages in various formats.

Webhooks

Configure webhooks to receive notifications when specific events occur in your project. Webhooks can be triggered by translation updates, review completions, task assignments, QA issue creation, and other events. This enables real-time integration with external systems and automated workflows.

GitHub Integration

The API supports GitHub integration for syncing translation files. Pull source files from GitHub repositories, automatically create keys from source files, and push translations back to GitHub via pull requests. The integration supports branch mapping and file filtering.

Over-the-Air Updates

Manage OTA (Over-the-Air) environments for mobile applications. Configure environments, set variable formats, and control how translations are delivered to mobile apps without requiring app store updates.

Quality Assurance

Access QA issues programmatically. The API can retrieve QA issues, dismiss false positives, and track translation quality metrics. QA checks include placeholder validation, spelling checks, variable consistency, and other quality indicators.

Comments and Collaboration

Manage comments on translations and keys. Create comments, resolve discussions, and track feedback from contributors. This enables programmatic workflow management for translation reviews.

API Permissions

The API uses a role-based permission system. When creating an API token, you can specify exactly which operations the token can perform. Permission groups include:

• Project: Read project information and edit project settings
• Keys: View, create, edit, and delete keys
• Translate: Write and review translations
• Languages: Add, edit, and delete languages
• Tasks: Create, edit, and delete translation tasks
• Screenshots: Upload and manage screenshots
• Glossary: Manage glossary terms
• Tags: Create and delete tags
• Webhooks: Manage webhook configurations
• GitHub Integration: Connect repositories and sync files
• Namespaces: Organize keys into namespaces
• Releases: Create and manage releases
• OTA Environments: Configure over-the-air update environments

This granular permission system allows you to create API keys with minimal necessary permissions, following security best practices.

Download and Export

The API provides flexible download options for translations. You can download translations in multiple formats including JSON, YAML, XLIFF, PO, properties files, PHP Laravel format, XCStrings, and i18n JSON format.

Download options include:

• Filtering by language, namespace, or translation status
• Selecting specific keys to include
• Choosing variable format (object, ICU, or i18n)
• Downloading as files or raw text
• Specifying release versions or latest translations
• Filtering by translation status (translated, reviewed, not translated)

File Upload

Import translation files directly through the API. Upload files in various formats, and the API will automatically parse and create keys and translations. Supported formats include JSON, XLIFF, PO, properties files, YAML, and other standard localization formats.

Rate Limiting

The API implements rate limiting using a moving request window. Rate limit information is included in response headers (X-RateLimit-*), allowing you to monitor your API usage and adjust request patterns accordingly.

Important considerations:

• Only one consecutive request is processed at a time per API key
• Rate limits vary based on your plan
• Check response headers to monitor your current usage
• For bulk operations, consider using batch endpoints when available

Getting Started

Creating an API Key

1. Navigate to your project settings in the Sejhey dashboard
2. Open the API Tokens section
3. Click Create API Token
4. Select the permissions your integration requires
5. Copy and securely store the generated API key

Note: API keys are only shown once when created. If you lose an API key, you'll need to create a new one.

Making Your First Request

Here's a basic example of retrieving all keys in a project:

curl -X GET "https://app.sejhey.com/api/v1/projects/{project_id}/keys" \
  -H "X-API-Key: your-api-key-here"

In JavaScript:

const response = await fetch(
  `https://app.sejhey.com/api/v1/projects/${projectId}/keys`,
  {
    headers: {
      'X-API-Key': 'your-api-key-here'
    }
  }
);

const keys = await response.json();

Downloading Translations

Download translations in your preferred format:

curl -X POST "https://app.sejhey.com/api/v1/projects/{project_id}/download" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "json",
    "selected_locales": ["en", "fr", "de"],
    "download_type": "file"
  }'

Creating Keys Programmatically

Create new translation keys in bulk:

const response = await fetch(
  `https://app.sejhey.com/api/v1/projects/${projectId}/keys/batch`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      keys: [
        { name: 'welcome.title', default_value: 'Welcome' },
        { name: 'welcome.subtitle', default_value: 'Get started' }
      ]
    })
  }
);

Documentation and Resources

Complete API documentation is available with detailed endpoint specifications, request/response examples, and interactive testing capabilities. The documentation includes:

• OpenAPI 3.0 specification for code generation and validation
• Interactive API explorer for testing endpoints
• Request and response examples for each endpoint
• Error code reference and troubleshooting guides

Access the full documentation here

The OpenAPI specification is also available in your project settings for integration with API clients, code generators, and testing tools.

Use Cases

The API enables various automation and integration scenarios:

CI/CD Integration: Automate translation downloads in deployment pipelines, ensuring production applications always have the latest translations.

Custom Translation Tools: Build specialized interfaces for managing translations, bulk editing tools, or integration dashboards tailored to your workflow.

External System Integration: Sync translations with content management systems, export to other localization platforms, or integrate with internal tools.

Automated Quality Checks: Programmatically review translations, run quality assurance checks, and generate reports on translation status.

Workflow Automation: Create and assign tasks automatically based on project changes, notify team members of updates, or trigger external processes via webhooks.

---

For more information and to get started with the API, visit app.sejhey.com or explore the API documentation.