---
title: "Get Suggested Segments"
method: GET
path: "/v1/matter-segments/suggestions"
tags: ["matter-segments"]
---

# Get Suggested Segments

`GET /v1/matter-segments/suggestions`

## Request

- Base URL: `https://app.tokumalabs.com/api`
- URL: `https://app.tokumalabs.com/api/v1/matter-segments/suggestions`
- Auth: OAuth 2
  - Password
  - Token URL: `v1/auth/token`

AI-suggested segments for a time entry, as bare ids.

For clients that mirror the matter tree locally — see
``SuggestedSegmentsResponse``. Returns an
empty list when no ``time_entry_id`` is given (the create-entry
dialog has no entry to suggest against yet).

Only segments the user may still assign are returned — a detection
recorded before its matter closed, or before the matter was
restricted away from them, is dropped here rather than left for the
client's mirror to catch. A matter the user is a participant of ranks
ahead of an equal score on one they are not, with the same factor
segment detection uses.

## Query parameters

- `time_entry_id` integer, nullable

## Response `200`

Successful Response

- SuggestedSegmentsResponse: Suggestions alone, for clients that mirror matters locally. The desktop app syncs clients / matters / segments through ``GET /api/v1/sync`` and computes "Recently used" from its own mirrored ``time_entries`` ⋈ ``time_entry_releases``. Suggestions are the one part it cannot derive: they are scored from ``activities.segment_confidence_*``, and activities are telemetry that is deliberately not synced. So this endpoint is what remains of the picker's network surface — a handful of ids, fetched once per dialog open.
  - `suggested` SuggestedSegmentRefDto[], required
    - `segment_id` string, required: Segment ID, in descending suggestion order

## Other responses

- `400`: Validation error or domain rule violation.
- `401`: Missing, expired, or invalid authentication.
- `403`: Authenticated but not permitted.
- `404`: Resource not found.
- `409`: Resource state conflict (duplicate, illegal transition).
- `422`: Request body failed schema validation.
- `500`: Server-side failure.

---

[API](https://skmtc.dev/tokumalabs/apis/tokuma-user-api.md) - [All operations](https://skmtc.dev/tokumalabs/apis/tokuma-user-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tokumalabs/apis/tokuma-user-api/revisions/1f8201af459b?raw)