william/iris_translation_v2
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Page: api reference
Pages
Home api reference implementation plan jobs and workflow local development open questions operations and scaling product quality and review runtime architecture setup and configuration storage and artifacts translation and retrieval
1 api reference
william le roux edited this page 2026-04-01 11:13:16 +03:00
Table of Contents

API Reference

This document lists the HTTP endpoints that are actually routed in apps/api/urls.py.

Related Docs

Current API Characteristics

  • all views inherit from a CSRF-exempt base view
  • /api/v1/* requires authentication by default
  • supported auth mechanisms are Django session auth and HTTP Basic auth
  • operator means any active authenticated user
  • admin means any active authenticated user who is staff, superuser, or a member of IRIS_API_ADMIN_GROUP
  • /health/live, /health/ready, and signed artifact downloads are intentionally public
  • JSON-body endpoints return structured errors in the form { "error": { "code", "message", ... } }
  • file-upload endpoints expect multipart form data

Actor identity for audit events now comes from the authenticated user. Compatibility fields such as submitted_by, changed_by, requested_by, cancelled_by, imported_by, and promoted_by may still be accepted by some endpoints, but they no longer override the recorded actor.

Health

Method Path Notes
GET /health/live Always returns service liveness
GET /health/ready Returns dependency checks and 503 when not ready

/health/ready reports checks for:

  • database
  • storage
  • aspose
  • broker
  • opensearch

Artifact Downloads

Method Path Notes
DELETE /api/v1/artifacts/{artifact_id} admin; deletes an expired artifact for a terminal job
GET /api/v1/artifacts/{artifact_id}/download Uses a signed token for local-download authorization

Jobs

Method Path Notes
POST /api/v1/jobs operator; create a job from a DOCX upload

| GET | /api/v1/jobs/{job_id} | operator; fetch a serialized job record |

| GET | /api/v1/jobs/{job_id}/stats | operator; fetch the job statistics snapshot |

| GET | /api/v1/jobs/{job_id}/verification-results | operator; fetch per-unit verification results | | GET | /api/v1/jobs/{job_id}/artifacts | operator; list artifacts with download links and retention data | | POST | /api/v1/jobs/{job_id}/process | operator; run synchronous processing through extraction, translation, QA, and reassembly | | POST | /api/v1/jobs/{job_id}/cancel | operator; cancel a job | | POST | /api/v1/jobs/{job_id}/rerun | operator; create a rerun job |

| POST | /api/v1/jobs/{job_id}/reassemble | operator; force DOCX reassembly |

| POST | /api/v1/jobs/{job_id}/tmx-export | operator; export TMX for review | | POST | /api/v1/jobs/{job_id}/tmx-import | operator; import reviewed TMX | | POST | /api/v1/jobs/{job_id}/replay | operator; build a replay package | | GET | /api/v1/jobs/{job_id}/compare | operator; compare with another job via other_job_id query param |

Job creation request

POST /api/v1/jobs requires multipart form data with:

  • file

  • project_code

  • domain_pack_code

  • source_language

  • target_language

Optional form fields:

  • external_reference

  • document_title

  • version_label

  • family_key

  • revision_strategy

  • submitted_by (accepted for compatibility but ignored for audit identity)

  • idempotency_key

  • metadata as JSON text

Comparison request

GET /api/v1/jobs/{job_id}/compare requires:

  • other_job_id query parameter

Audit And Reporting

Method Path Notes
GET /api/v1/audit-events admin; filtered audit-event search

| GET | /api/v1/projects/{project_code}/review-coverage | operator; project review coverage summary |

Audit-event filters

Supported query parameters:

  • job_id

  • action

  • actor

  • correlation_id

  • target_model

  • project_code

  • date_from

  • date_to

  • limit

limit must be an integer from 1 to 500.

Domain Packs

Method Path Notes

| GET | /api/v1/domain-packs | operator; list all domain packs |

Projects

Method Path Notes
GET /api/v1/projects operator; list projects

| POST | /api/v1/projects | admin; create a project |

| PATCH | /api/v1/projects/{project_code} | admin; update a project |

Project list filters

Supported query parameters:

  • domain_pack_code

  • q

  • is_active

Project create fields

Required JSON fields:

  • domain_pack_code

  • code

  • name

Optional JSON fields:

  • retention_days

  • metadata

  • is_active

  • changed_by (accepted for compatibility but ignored for audit identity)

Provider Profiles

Method Path Notes
GET /api/v1/provider-profiles operator; list provider profiles
POST /api/v1/provider-profiles admin; create a provider profile

| PATCH | /api/v1/provider-profiles/{provider_code} | admin; update a provider profile |

Provider-profile list filters

Supported query parameters:

  • provider_kind

  • q

  • is_active

Provider-profile create fields

Required JSON fields:

  • code

  • name

  • provider_kind

  • model_name

Optional JSON fields:

  • endpoint
  • config
  • is_active
  • changed_by (accepted for compatibility but ignored for audit identity)

Language Pair Policies

| Method | Path | Notes |

| --- | --- | --- |

| GET | /api/v1/language-pair-policies | operator; list policies | | POST | /api/v1/language-pair-policies | admin; create a policy | | PATCH | /api/v1/language-pair-policies/{policy_id} | admin; update a policy |

Language-pair-policy list filters

Supported query parameters:

  • domain_pack_code
  • source_language
  • target_language
  • provider_profile_code
  • is_active

Language-pair-policy create fields

Required JSON fields:

  • domain_pack_code

  • source_language

  • target_language

Optional JSON fields:

  • provider_profile_code

  • policy_version

  • qa_pack

  • low_resource_mode

  • strict_review_required

  • model_policy

  • review_policy

  • fallback_policy

  • is_active

  • changed_by (accepted for compatibility but ignored for audit identity)

Glossaries

Method Path Notes
GET /api/v1/glossaries operator; list glossary entries

| POST | /api/v1/glossaries/import | admin; import glossary rows from CSV |

Glossary list filters

Supported query parameters:

  • domain_pack_code

  • project_code

  • family_key

  • source_language

  • target_language

  • enforcement_level

  • scope (domain, project, or family)

  • q

  • is_active

Glossary import request

POST /api/v1/glossaries/import expects multipart form data with:

  • file
  • optional imported_by compatibility field that does not override audit identity

Memory

Method Path Notes
GET /api/v1/memory/candidates operator; list candidate memory entries
DELETE /api/v1/memory/candidates/{candidate_id} admin; deactivate a candidate memory entry
GET /api/v1/memory/approved operator; list approved memory entries
DELETE /api/v1/memory/approved/{entry_id} admin; deactivate an approved memory entry

| POST | /api/v1/memory/promotions | admin; promote candidate memory into approved memory |

Candidate-memory filters

Supported query parameters:

  • domain_pack_code

  • project_code

  • family_key

  • source_language

  • target_language

  • promotion_status

  • source_job_id

  • q

  • is_active

Approved-memory filters

Supported query parameters:

  • domain_pack_code

  • project_code

  • family_key

  • source_language

  • target_language

  • approval_source

  • q

  • is_active For exact field names, see apps/api/serializers.py. For job progression and review behavior, see Jobs And Workflow.