---
title: "Create a new segment"
method: POST
path: "/v1/assets/{asset_id}/segments/"
---

# Create a new segment

`POST /v1/assets/{asset_id}/segments/`

## Request

- Base URL: `https://app.iconik.io/API/assets`
- URL: `https://app.iconik.io/API/assets/v1/assets/{asset_id}/segments/`
- Auth: none declared. Required headers: `App-ID`, `Auth-Token`
- TypeScript: <https://skmtc.dev/iconik/apis/iconik-assets/docs/v1/assets/:asset_id/segments/post.ts> (a function with typed inputs; its response is checked against the schema)

<br/>Comments are segments with `segment_type` set to `COMMENT`.<br/>A comment can be created directly with status `AWAITED`. When `status` is not<br/>specified the segment is created with status `ACTIVE`.<br/>An `AWAITED` comment is not posted yet: nobody is notified about it, and segment<br/>listings leave it out unless they filter on `status`, until it is updated to `ACTIVE`.<br/><br/>On a subclip, time-based metadata segments (TAG, GENERIC, TRANSCRIPTION, SHOT,<br/>SEMANTIC_TRANSCRIPTION) are created on the subclip's original asset, under the<br/>version the subclip was cut from. A `version_id`, if given, must be that version or<br/>one of the subclip's own; any other is rejected with 400.<br/>Comments are segments with `segment_type` set to `COMMENT`.<br/>A comment can be created directly with status `AWAITED`. When `status` is not<br/>specified the segment is created with status `ACTIVE`.<br/>An `AWAITED` comment is not posted yet: nobody is notified about it, and segment<br/>listings leave it out unless they filter on `status`, until it is updated to `ACTIVE`.<br/><br/>On a subclip, time-based metadata segments (TAG, GENERIC, TRANSCRIPTION, SHOT,<br/>SEMANTIC_TRANSCRIPTION) are created on the subclip's original asset, under the<br/>version the subclip was cut from. A `version_id`, if given, must be that version or<br/>one of the subclip's own; any other is rejected with 400.
Required roles:
 - can_create_segments

## Path parameters

- `asset_id` string, required

## Query parameters

- `ignore_reindexing` boolean
- `should_reindex_assets` boolean

## Headers

- `App-ID` string, required
- `Auth-Token` string, required
- `Share-User-Email` string

## Request body

- SegmentSchema
  - `asset_id` string, uuid
  - `date_created` string, date-time
  - `date_modified` string, date-time
  - `drawing` DrawingSchema
    - `primitives` DrawingPrimitiveSchema[]
      - `color` string
      - `opacity` number
      - `points` DrawingPointSchema[]
        - `x` number, required
        - `y` number, required
      - `text` string
      - `type` 'LINE' | 'RECTANGLE' | 'ARROW' | 'ELLIPSE' | 'PENCIL' | 'TEXT' | 'CROSS', required
      - `width` number
    - `version` integer, nullable
  - `external_id` string, nullable
  - `face_bounding_boxes` FaceBoundingBoxSchema[], nullable
    - `bounding_box` number[]
    - `landmarks` FaceLandmark[], nullable
      - `x` number, required
      - `y` number, required
    - `person_version_face_id` string, uuid, required
    - `timestamp_ms` integer
  - `has_attachments` boolean: Whether the comment has attachments in iconik_files
  - `has_drawing` boolean
  - `id` string, uuid
  - `is_internal` boolean, nullable: If set to true, the segment is only visible to internal iconik users
  - `keyframe_id` string, uuid, nullable
  - `metadata` object
  - `metadata_view_id` string, uuid, nullable
  - `parent_id` string, uuid
  - `path` string
  - `person_id` string, uuid, nullable
  - `project_id` string, uuid, nullable: ID of a project if the segment is created from a project
  - `segment_checked` boolean
  - `segment_color` string
  - `segment_text` string, nullable
  - `segment_track` string, nullable
  - `segment_type` 'MARKER' | 'QC' | 'GENERIC' | 'COMMENT' | 'TAG' | 'TRANSCRIPTION' | 'SCENE' | 'SHOT' | 'PERSON' | 'SEMANTIC_TRANSCRIPTION', required
  - `semantic_transcription` SemanticTranscription
    - `cut_reasons` string[], nullable
    - `embedding` string, nullable
    - `embedding_dim` integer, nullable
    - `embedding_encoding` string, nullable
    - `embedding_model` string, nullable
    - `embedding_model_version` string, nullable
    - `entities` SemanticTranscriptionEntity[], nullable
      - `label` string, nullable
      - `text` string, required
    - `language` string, nullable
    - `speaker_count` string, nullable
    - `tone` string, nullable
    - `topics` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `track_id` string, nullable
    - `valence` string, nullable
  - `share_id` string, uuid, nullable: ID of a share if the segment is created from a share
  - `share_session_id` string, uuid, nullable
  - `share_user_email` string, email, nullable
  - `shot` Shot
    - `actions` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `animal_species` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `brand_logo` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `camera_angle` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `caption` string, nullable
    - `color_palette` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `composition` string, nullable
    - `dog_breeds` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `dominant_hue` string, nullable
    - `embedding` string, nullable
    - `embedding_dim` integer, nullable
    - `embedding_encoding` string, nullable
    - `embedding_model` string, nullable
    - `embedding_model_version` string, nullable
    - `facial_expression` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `keyframe_ts` integer
    - `light_key` string, nullable
    - `light_side` string, nullable
    - `light_style` string[], nullable
    - `light_time` string, nullable
    - `mood` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `mood_valence` string, nullable
    - `movement` string[], nullable
    - `objects` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `ocr_text` string, nullable
    - `orientation` string, nullable
    - `people_age_range` string[], nullable
    - `people_bucket` string, nullable
    - `people_count` integer, nullable
    - `people_features` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `people_gender` string[], nullable
    - `place` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `resolution` string, nullable
    - `scale_rank` integer, nullable
    - `season` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `sensitive_content` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `setting` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `shot_scale` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `sport_type` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `subject_type` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `time_of_day` string, nullable
    - `track_id` string, nullable
    - `weather` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
  - `status` 'ACTIVE' | 'DELETED' | 'AWAITED'
  - `subclip_id` string, uuid
  - `time_end_milliseconds` integer, nullable
  - `time_start_milliseconds` integer, nullable
  - `top_level` boolean
  - `transcription` TranscriptionType
    - `speaker` integer, nullable
    - `words` TranscriptionElementType[], required
      - `end_ms` integer, required
      - `score` number
      - `start_ms` integer, required
      - `value` string, required
  - `transcription_id` string, uuid, nullable
  - `user_first_name` string
  - `user_id` string, uuid
  - `user_info` User
    - `email` string, email
    - `first_name` string
    - `id` string, uuid
    - `last_name` string
    - `photo` string
    - `photo_big` string
    - `photo_small` string
  - `user_last_name` string
  - `user_photo` string
  - `version_id` string, uuid

## Response `201`

Returns a created segment

- SegmentSchema
  - `asset_id` string, uuid
  - `date_created` string, date-time
  - `date_modified` string, date-time
  - `drawing` DrawingSchema
    - `primitives` DrawingPrimitiveSchema[]
      - `color` string
      - `opacity` number
      - `points` DrawingPointSchema[]
        - `x` number, required
        - `y` number, required
      - `text` string
      - `type` 'LINE' | 'RECTANGLE' | 'ARROW' | 'ELLIPSE' | 'PENCIL' | 'TEXT' | 'CROSS', required
      - `width` number
    - `version` integer, nullable
  - `external_id` string, nullable
  - `face_bounding_boxes` FaceBoundingBoxSchema[], nullable
    - `bounding_box` number[]
    - `landmarks` FaceLandmark[], nullable
      - `x` number, required
      - `y` number, required
    - `person_version_face_id` string, uuid, required
    - `timestamp_ms` integer
  - `has_attachments` boolean: Whether the comment has attachments in iconik_files
  - `has_drawing` boolean
  - `id` string, uuid
  - `is_internal` boolean, nullable: If set to true, the segment is only visible to internal iconik users
  - `keyframe_id` string, uuid, nullable
  - `metadata` object
  - `metadata_view_id` string, uuid, nullable
  - `parent_id` string, uuid
  - `path` string
  - `person_id` string, uuid, nullable
  - `project_id` string, uuid, nullable: ID of a project if the segment is created from a project
  - `segment_checked` boolean
  - `segment_color` string
  - `segment_text` string, nullable
  - `segment_track` string, nullable
  - `segment_type` 'MARKER' | 'QC' | 'GENERIC' | 'COMMENT' | 'TAG' | 'TRANSCRIPTION' | 'SCENE' | 'SHOT' | 'PERSON' | 'SEMANTIC_TRANSCRIPTION', required
  - `semantic_transcription` SemanticTranscription
    - `cut_reasons` string[], nullable
    - `embedding` string, nullable
    - `embedding_dim` integer, nullable
    - `embedding_encoding` string, nullable
    - `embedding_model` string, nullable
    - `embedding_model_version` string, nullable
    - `entities` SemanticTranscriptionEntity[], nullable
      - `label` string, nullable
      - `text` string, required
    - `language` string, nullable
    - `speaker_count` string, nullable
    - `tone` string, nullable
    - `topics` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `track_id` string, nullable
    - `valence` string, nullable
  - `share_id` string, uuid, nullable: ID of a share if the segment is created from a share
  - `share_session_id` string, uuid, nullable
  - `share_user_email` string, email, nullable
  - `shot` Shot
    - `actions` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `animal_species` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `brand_logo` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `camera_angle` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `caption` string, nullable
    - `color_palette` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `composition` string, nullable
    - `dog_breeds` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `dominant_hue` string, nullable
    - `embedding` string, nullable
    - `embedding_dim` integer, nullable
    - `embedding_encoding` string, nullable
    - `embedding_model` string, nullable
    - `embedding_model_version` string, nullable
    - `facial_expression` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `keyframe_ts` integer
    - `light_key` string, nullable
    - `light_side` string, nullable
    - `light_style` string[], nullable
    - `light_time` string, nullable
    - `mood` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `mood_valence` string, nullable
    - `movement` string[], nullable
    - `objects` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `ocr_text` string, nullable
    - `orientation` string, nullable
    - `people_age_range` string[], nullable
    - `people_bucket` string, nullable
    - `people_count` integer, nullable
    - `people_features` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `people_gender` string[], nullable
    - `place` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `resolution` string, nullable
    - `scale_rank` integer, nullable
    - `season` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `sensitive_content` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `setting` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `shot_scale` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `sport_type` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `subject_type` UnderstandingTag[], nullable
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
    - `time_of_day` string, nullable
    - `track_id` string, nullable
    - `weather` UnderstandingTag
      - `label` string, required
      - `level` string, nullable
      - `score` number, nullable
  - `status` 'ACTIVE' | 'DELETED' | 'AWAITED'
  - `subclip_id` string, uuid
  - `time_end_milliseconds` integer, nullable
  - `time_start_milliseconds` integer, nullable
  - `top_level` boolean
  - `transcription` TranscriptionType
    - `speaker` integer, nullable
    - `words` TranscriptionElementType[], required
      - `end_ms` integer, required
      - `score` number
      - `start_ms` integer, required
      - `value` string, required
  - `transcription_id` string, uuid, nullable
  - `user_first_name` string
  - `user_id` string, uuid
  - `user_info` User
    - `email` string, email
    - `first_name` string
    - `id` string, uuid
    - `last_name` string
    - `photo` string
    - `photo_big` string
    - `photo_small` string
  - `user_last_name` string
  - `user_photo` string
  - `version_id` string, uuid

## Other responses

- `400`: Bad request
- `401`: Token is invalid
- `403`: User is not allowed to leave a comment
- `404`: Asset, share, share user or version does not exist
- `default`: Error response

---

[API](https://skmtc.dev/iconik/apis/iconik-assets.md) - [All operations](https://skmtc.dev/iconik/apis/iconik-assets/llms.txt) - [OpenAPI document](https://skmtc.dev/iconik/apis/iconik-assets/revisions/62580d9e640e?raw)