> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linguolink.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Push translations (import)

> Bulk import a JSON translation file as a background job (or preview it with `dryRun`). Powers `lingulink push`.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/push
openapi: 3.0.0
info:
  contact:
    email: support@linguolink.dev
    name: LinguLink Support
  description: Translation management API for LinguLink platform
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  title: LinguLink API v1
  version: 1.0.0
servers:
  - description: Development server
    url: http://localhost:3000
  - description: Production server
    url: https://linguolink.dev
security: []
tags:
  - description: API key authentication and validation
    name: Authentication
  - description: API key management operations
    name: API Keys
  - description: Translation management operations
    name: Translations
  - description: Endpoints the `lingulink` CLI's pull/push commands call
    name: CLI
  - description: Project metadata and translation coverage
    name: Projects
paths:
  /api/v1/push:
    post:
      tags:
        - CLI
      summary: Push translations (import)
      description: >-
        Bulk import a JSON translation file as a background job (or preview it
        with `dryRun`). Powers `lingulink push`.
      operationId: pushTranslations
      requestBody:
        content:
          application/json:
            schema:
              properties:
                content:
                  description: >-
                    Raw JSON file content. Nested objects are flattened into
                    dot-separated keys (e.g. {"auth":{"title":"Sign in"}}
                    becomes the key "auth.title"). A null value imports as the
                    literal string "null"; array values are flattened into
                    index-suffixed keys (e.g. "key.0", "key.1") rather than
                    being rejected.
                  example: '{"welcome.message": "Welcome to our app"}'
                  type: string
                dryRun:
                  default: false
                  description: Validate and preview changes without starting an import
                  type: boolean
                format:
                  default: json
                  description: Only JSON is supported in v1
                  enum:
                    - json
                  type: string
                importMode:
                  default: merge
                  description: Whether to merge with or replace existing translations
                  enum:
                    - merge
                    - replace
                  type: string
                language:
                  description: Target language code for the imported values
                  example: de
                  type: string
                projectId:
                  description: Project UUID
                  format: uuid
                  type: string
                status:
                  default: approved
                  description: Status to assign to imported translation rows
                  enum:
                    - draft
                    - pending
                    - approved
                    - needs_review
                  type: string
              required:
                - content
                - language
                - projectId
              type: object
        description: Bulk import request
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                dryRun: true
                importMode: merge
                language: de
                rowCount: 128
                toCreate: 40
                toUpdate: 88
              schema:
                properties:
                  dryRun:
                    example: true
                    type: boolean
                  importMode:
                    enum:
                      - merge
                      - replace
                    type: string
                  language:
                    type: string
                  rowCount:
                    type: integer
                  toCreate:
                    type: integer
                  toUpdate:
                    type: integer
                type: object
          description: >-
            Dry-run preview — only returned when `dryRun: true`. No data is
            written.
        '202':
          content:
            application/json:
              example:
                jobId: 5f6e8b2a-3b7a-4c2a-9c37-8e6f8d6a9b10
                runId: run_9c2a3b7a4c2a9c37
              schema:
                properties:
                  jobId:
                    description: Poll via GET /api/v1/jobs/{jobId}
                    type: string
                  runId:
                    description: Trigger.dev run identifier
                    type: string
                type: object
          description: Import accepted and running as a background job.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          content:
            application/json:
              example:
                error: Payload too large
              schema:
                $ref: '#/components/schemas/Error'
          description: Payload exceeds the 12 MB / 50,000 row cap.
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
        - OAuth2: []
components:
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad request
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Authentication required
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Resource not found
    InternalServerError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal server error
  schemas:
    Error:
      properties:
        details:
          description: Additional error details (development only)
          type: string
        error:
          description: Error message
          type: string
        timestamp:
          description: Error timestamp
          format: date-time
          type: string
      required:
        - error
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API Key
      description: 'Enter your API key in the format: Bearer <api_key>'
      scheme: bearer
      type: http
    OAuth2:
      description: >-
        Exchange your API key (as client_secret) for a short-lived access token.
        The playground fetches and applies the token automatically.
      flows:
        clientCredentials:
          scopes:
            admin: Administrate translations and API keys
            export:read: Export translations
            translations:read: Read translations
            translations:write: Create or update translations
          tokenUrl: https://linguolink.dev/api/v1/auth/token
      type: oauth2

````