Migration: Text Content API

[Tech-lo]

OpenPecha API

Step 1 — Get edition ID

GET /v2/texts/{text_id}/editions?edition_type=critical

Param	Type	In	Required	Description
text_id	string	path	Yes	OP expression ID
edition_type	string	query	No	diplomatic, critical, or all (default)

Response (200) — text_id=5wPLZFpQ6gqRq4WVLz1aE:

[
  {
    "id": "NTC6a2yD6OOwoJtZnUuIu",
    "text_id": "5wPLZFpQ6gqRq4WVLz1aE",
    "type": "critical",
    "source": "www.openpecha.org",
    "bdrc": null,
    "wiki": null,
    "colophon": null,
    "incipit_title": null,
    "alt_incipit_titles": null
  }
]

Code	Description
200	Editions retrieved successfully
400	Error with request
404	Resource not found
500	Internal server error

Step 2a — Get segmentation annotations

GET /v2/editions/{edition_id}/annotations?type=segmentation

Param	Type	In	Required	Description
edition_id	string	path	Yes	Edition (manifestation) ID from Step 1
type	array<string>	query	No	Annotation type filter. Options: segmentation, alignment, pagination, bibliography, durchen

Response (200) — edition_id=NTC6a2yD6OOwoJtZnUuIu:

{
  "segmentations": [
    {
      "id": "riqEEIIrGSHXa6xRWb7mH",
      "segments": [
        {
          "id": "gDec9pSWQF9TQSGytfrFZ",
          "lines": [{ "end": 150, "start": 0 }],
          "manifestation_id": "NTC6a2yD6OOwoJtZnUuIu",
          "text_id": "5wPLZFpQ6gqRq4WVLz1aE"
        },
        {
          "id": "9zU8p6Qk5cPlhYV9bbQvP",
          "lines": [{ "end": 421, "start": 150 }],
          "manifestation_id": "NTC6a2yD6OOwoJtZnUuIu",
          "text_id": "5wPLZFpQ6gqRq4WVLz1aE"
        }
      ]
    }
  ]
}

Step 2b — Get durchen annotations

GET /v2/editions/{edition_id}/annotations?type=durchen

Same endpoint, different type param.

Response (200) — edition_id=NTC6a2yD6OOwoJtZnUuIu:

{
  "durchen_notes": [
    {
      "id": "lSTNFAFzMmr3mxQLrSHRu",
      "span": { "end": 149, "start": 145 },
      "text": "མེད། /འོ།/འོ།།"
    },
    {
      "id": "L5V0yrA0h0KHowBgsIHU6",
      "span": { "end": 356, "start": 328 },
      "text": "མེ་རིང་འཚེང་འཇོམས་ཀྱི་ /འོ།/མེ་རི། །"
    }
  ]
}

Code	Description
200	Annotations retrieved successfully
404	Resource not found
500	Internal server error

Step 3 — Get base text content

GET /v2/editions/{edition_id}/content

Param	Type	In	Required	Description
edition_id	string	path	Yes	Edition (manifestation) ID from Step 1
span_start	int	query	No	Start character position (use with span_end)
span_end	int	query	No	End character position (use with span_start)

Response (200): JSON string (application/json content type). Use segment span offsets from Step 2a to split into segments. Optional span_start/span_end allows fetching a substring instead of the full base text.

Note: Currently returning 500 on dev for all tested edition IDs.

Flow summary: 3 OP calls (editions → annotations → content) + client-side span splitting replaces 1 WeBuddhist POST call.

---

Replaces WeBuddhist API:

POST /api/v1/texts/{text_id}/details

Param	Type	In	Required	Description
text_id	string	path	Yes	WeBuddhist internal ID

Request body:

Field	Type	Description
content_id	string	Table of contents ID
version_id	string	Version ID
segment_id	string	Segment ID
section_id	string	Section ID
size	int	Number of segments to return
direction	string	Pagination direction (next or previous)

Response (200) — text_id=e159959d-2c0c-4f48-b02c-fbdc8c4a98e3:

{
  "text_detail": {
    "id": "e159959d-2c0c-4f48-b02c-fbdc8c4a98e3",
    "pecha_text_id": "XVqq55pnANEKri9536Wa4",
    "title": "The Way of the Bodhisattva",
    "language": "en",
    "group_id": "76060053-0121-40d0-ba34-9c55ea7df2f3",
    "type": "version",
    "summary": "",
    "is_published": false,
    "created_date": "2025-11-27 16:22:29",
    "updated_date": "2025-11-27 16:22:29",
    "published_date": "2025-11-27 16:22:29",
    "published_by": "",
    "categories": ["692876ab70bf66f003b07d6a"],
    "views": 0,
    "likes": [],
    "source_link": "openpecha.org",
    "ranking": null,
    "license": "unknown"
  },
  "content": {
    "id": "13830c91-57ef-4456-bcdc-58ede76c043a",
    "text_id": "e159959d-2c0c-4f48-b02c-fbdc8c4a98e3",
    "sections": [
      {
        "id": "5b23c7c5-d3e5-4f53-bf04-f5f378489b40",
        "title": "1",
        "section_number": 1,
        "parent_id": null,
        "segments": [
          {
            "segment_id": "048576e2-b2bc-4275-9d6c-220ca7357f3c",
            "segment_number": 1,
            "content": "The Way of the Bodhisattva",
            "translation": null
          },
          {
            "segment_id": "13a81958-f751-4baf-833c-96196ded47cf",
            "segment_number": 2,
            "content": "In Sanskrit: Bodhisattvacharyavatara",
            "translation": null
          }
        ],
        "sections": [],
        "created_date": null,
        "updated_date": null,
        "published_date": null
      }
    ]
  },
  "size": 20,
  "pagination_direction": "next",
  "current_segment_position": 1,
  "total_segments": 929
}

Code	Description
200	Successful Response
422	Validation Error

---

Response Mapping

OP flow: GET /v2/texts/{id}/editions → GET /v2/editions/{id}/annotations → GET /v2/editions/{id}/content + client-side span splitting
Replaces: POST /api/v1/texts/{id}/details

WeBuddhist	OpenPecha	Notes
text_detail.id	—	WeBuddhist-only
text_detail.pecha_text_id	editions[].id (Step 1)	WeBuddhist stored edition ID
text_detail.title	—	Not returned by editions endpoint. Available from GET /v2/texts/{id} expression
text_detail.language	—	Same as above
text_detail.type	editions[].type (Step 1)	OP: critical / diplomatic. WeBuddhist: version
text_detail.license	—	Not in editions endpoint. Available from expression or need separate call
text_detail.group_id	—	WeBuddhist-only
text_detail.summary	—	Deprecated
text_detail.is_published	—	To be removed
text_detail.created_date	—	To be removed
text_detail.updated_date	—	To be removed
text_detail.published_date	—	To be removed
text_detail.published_by	—	To be removed
text_detail.categories	—	WeBuddhist-only
text_detail.views	—	WeBuddhist-only
text_detail.likes	—	WeBuddhist-only
text_detail.source_link	editions[].source (Step 1)	WeBuddhist: "openpecha.org". OP: "www.openpecha.org"
text_detail.ranking	—	To be removed
content.id	—	WeBuddhist-only
content.text_id	—	WeBuddhist-only
content.sections[].id	—	WeBuddhist-only. OP has no section concept
content.sections[].title	—	WeBuddhist-only
content.sections[].section_number	—	WeBuddhist-only
content.sections[].parent_id	—	WeBuddhist-only
content.sections[].segments[].segment_id	segmentations[].segments[].id (Step 2a)	Direct mapping
content.sections[].segments[].segment_number	—	WeBuddhist-only. OP uses span order instead
content.sections[].segments[].content	Base text (Step 3) + segments[].lines[].start/end (Step 2a)	OP: client must slice base text using span offsets. WeBuddhist: pre-split content string
content.sections[].segments[].translation	—	WeBuddhist-only (always null in tested data)
size	—	WeBuddhist pagination
pagination_direction	—	WeBuddhist pagination
current_segment_position	—	WeBuddhist pagination
total_segments	—	WeBuddhist pagination. Can be derived from segmentations[].segments array length
—	editions[].source (Step 1)	Source of the edition
—	editions[].colophon (Step 1)	New field
—	editions[].incipit_title (Step 1)	New field
—	editions[].alt_incipit_titles (Step 1)	New field
—	segments[].manifestation_id (Step 2a)	New. Links segment back to edition
—	segments[].text_id (Step 2a)	New. Links segment back to expression
—	durchen_notes[] (Step 2b)	New. Variant readings with span offsets