API Reference

The Langsys API provides a RESTful interface for managing translations, projects, and organizations. This page covers the essentials — for full endpoint details, see the interactive API documentation.

Base URL

https://api.langsys.dev

Authentication

The API supports two authentication methods. Every endpoint accepts at least one of these — most accept both.

Project API Keys

Project API keys are designed for integrating Langsys into your own apps and websites. Pass the key in the X-Authorization header:

X-Authorization: YOUR_PROJECT_API_KEY

Keys are scoped to a single project and come in two modes:

• Read mode — fetch translations, list available languages, and access utility endpoints
• Write mode — everything in read mode, plus the ability to create new translatable items and translations

This is the right choice when you need to pull translations into your frontend, sync content from a CMS, or submit new strings programmatically.

You can create and manage project API keys from Project Settings → API Keys.

User Bearer Tokens

User tokens grant access to any API endpoint that the authenticated user has permission to use — including organization management, billing, project configuration, and all translation operations.

Pass the token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

Tokens are obtained via the POST /auth/login endpoint and are suited for admin tools, CI/CD pipelines, or when connecting through an MCP client.

Which should I use?

	Project API Key	User Bearer Token
Header	X-Authorization	Authorization: Bearer
Scope	Single project	All user permissions
Access	Translations, utilities	All endpoints
Use case	App/site integration	Admin tools, CI/CD, MCP
Created from	Project Settings → API Keys	POST /auth/login

Rate Limiting

Plan	Requests per hour
Free	100
Pro	1,000
Enterprise	10,000

Rate limit headers are included in every response:

• X-RateLimit-Limit — your plan’s hourly limit
• X-RateLimit-Remaining — requests remaining in the current window

Response Format

All responses return JSON with a consistent structure.

Success

{
  "success": true,
  "data": {},
  "message": "Operation completed successfully"
}

Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "field": ["The field is required"]
    }
  }
}

Common error codes:

• VALIDATION_ERROR — invalid input data
• UNAUTHORIZED — missing or invalid token
• NOT_FOUND — resource does not exist
• RATE_LIMIT_EXCEEDED — too many requests

Common Endpoints

Organizations

Method	Endpoint	Description
GET	/organizations	List organizations
POST	/organizations	Create organization
GET	/organizations/{id}	Get organization

Projects

Method	Endpoint	Description
GET	/projects	List projects
POST	/projects	Create project
GET	/projects/{id}	Get project
PUT	/projects/{id}	Update project

Translatable Items

Method	Endpoint	Description
GET	/translatable-items	List translatable items
POST	/translatable-items	Create item
GET	/translatable-items/{id}	Get item
PUT	/translatable-items/{id}	Update item

Translations

Method	Endpoint	Description
GET	/translations	List translations
POST	/translations	Create translation
GET	/translations/{id}	Get translation
PUT	/translations/{id}	Update translation

For the complete list of endpoints with parameters, request bodies, and response schemas, see the interactive API docs.

Next Steps

• Connect via MCP — use the API directly from AI assistants
• Interactive API Reference — browse and test all endpoints