# Promote a focus segment

Promote a ready focus segment into a saved library track. Returns `201 Created` with the new track. The track is added to the caller's library.

Use this to keep a focus segment you liked. A session or segment you do not own returns `404`.

## Path parameters

**`organization_id`** string required

The organization the session is scoped to. The caller must belong to it.

**`session_id`** string required

The focus session id (`mfocus_`-prefixed).

**`segment_index`** integer required

Zero-based index of the ready segment to promote.

## Returns

The created track.

**`track_id`** string · Id of the created track (`mtrack_`-prefixed).

**`title`** string · Title of the promoted track.

**`engine`** string · Internal engine key the track was generated with.

**`licence_class`** string · Neutral licence tier: `commercial_cleared`, `commercial_enterprise`, `personal_only`, or `unclear`.

**`measured_duration_seconds`** number · Measured duration of the track in seconds.

Example

```bash cURL
curl -X POST "https://api.aitronos.com/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d/segments/0/promote" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python SDK
from aitronos import Aitronos  # pip install aitronos-sdk

client = Aitronos(api_key="your-api-key")

track = client.post(
    "/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d/segments/0/promote"
)
print(track["track_id"])
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.post(
    "https://api.aitronos.com/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d/segments/0/promote",
    headers={"X-API-Key": api_key},
)
print(response.json()["track_id"])
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch(
  'https://api.aitronos.com/v1/music/org_abc123/focus/sessions/mfocus_7c2a9f4e1b8d/segments/0/promote',
  { method: 'POST', headers: { 'X-API-Key': apiKey } }
);

const track = await response.json();
console.log(track.track_id);
```

**Response:**


```json 201 Created
{
  "track_id": "mtrack_b4d9e1c6a72f",
  "title": "Focus Session — Segment 1",
  "engine": "studio",
  "licence_class": "personal_only",
  "measured_duration_seconds": 120.4
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "system_message": "Focus segment not found or not ready",
    "type": "client_error",
    "status": 404,
    "details": { "session_id": "mfocus_7c2a9f4e1b8d", "segment_index": 0 },
    "trace_id": "req_jkl012mno",
    "timestamp": "2026-06-28T10:30:00Z"
  }
}
```

## Related Resources

- [Get a focus session](/docs/api-reference/music/get-focus-session)
- [List saved tracks](/docs/api-reference/music/list-tracks)
- [Save a track](/docs/api-reference/music/save-track)