---
title: "Register"
method: POST
path: "/v1/session/register"
---

# Register

`POST /v1/session/register`

Register a new session

## Request body

- PublicSessionInput — Only add the fields necessary to show to users.
  - `id` string — Session unique ramdom identifier.
  - `user_id` string, required — The user ID this session belongs to.
  - `org_id` string, required — The organization ID this session belongs to.
  - `model` ModelInfoInput, required — Describes a Sec-Gemini model configuration.
    - `model_name` string, required — The string used to identify the model.
    - `version` string, required — The version of the model.
    - `use_experimental` boolean — Whether to use experimental sub agents and tools.
    - `model_string` string, required — The string used to identify a model configuration.
    - `description` string, nullable — A brief description of the model.
    - `toolsets` OptionalToolSet[] — Toggable tools used by the model.
      - `name` string, required — The name of the toolset.
      - `version` integer, required — The version of the toolset.
      - `description` string, nullable, required — A brief description of the toolset.
      - `vendor` ToolSetVendor, required — Vendor Toolsets info.
        - `name` string, required — The name of the vendor providing the tool or agent.
        - `description` string, required — A brief description of the vendor.
        - `url` string, required — The URL of vendor.
        - `svg` string, required — The SVG icon of the vendor.
      - `is_enabled` boolean, required — Whether the bundle is enabled by default or not.
      - `is_enabled_by_default` boolean, required — Whether the bundle is enabled by default or not.
      - `is_enabled_by_default_in_incognito` boolean, required — Whether this tool is enabled in incognito mode by default.
      - `is_experimental` boolean, required — Whether the toolset is experimental or not.
  - `ttl` integer, required — The time to live of the session in seconds.
  - `language` string — The iso-code of the session language.
  - `turns` integer — The number of turns in the session.
  - `name` string, required — Human readable session name.
  - `description` string, required — A brief description to help users remember what the session is about.
  - `create_time` number — The Unix timestamp of when the session was created.
  - `update_time` number — The Unix timestamp of when the session was last updated.
  - `num_messages` integer — The number of messages in the session.
  - `messages` MessageInput[] — The list of messages comprising the session so far.
    - `id` string — A unique identifier for the message - uuid4 int.
    - `parent_id` string — The ID of the parent message.
    - `turn` string — The turn identifier is used to group/message are part of the same conversation turn.
    - `group` string — The Group ID (UUID4) identify messages part of the same generation or action.
    - `actor` string — The actor of the message - user or agent.
    - `role` 'user' | 'agent' | 'system' — Describe the role associated with the completion
    - `timestamp` integer — DEPRECATED: The Unix timestamp (in seconds) of when the message was created.
    - `created_at` number — The Unix timestamp (in seconds, including fractional parts) indicating when the message was created.
    - `message_type` 'result' | 'source' | 'debug' | 'info' | 'error' | 'thinking' | 'update' | 'delete' | 'confirmation_request' | 'confirmation_response' | 'query', required — Type of message
    - `icon` string, nullable — Custom svg icon to use in the UI.
    - `text_color` string, nullable — Custom text color to use in the UI.
    - `title` string, nullable — Descripting title of the message.
    - `state` 'undefined' | 'start' | 'end' | 'query' | 'running_agent' | 'agent_done' | 'coding' | 'code_result' | 'calling_tool' | 'tool_result' | 'generating' | 'answering' | 'thinking' | 'planning' | 'reviewing' | 'understanding' | 'retrieving' | 'grounding'
    - `content` string, nullable — The content of the message encoded as utf-8 bytes.
    - `mime_type` 'text/plain' | 'text/markdown' | 'text/serialized-json' | 'application/octet-stream' | 'image/jpeg' | 'image/png' | 'image/tiff' | 'image/gif' | 'image/svg+xml' | 'image/webp' | 'image/avif' | 'audio/wav' | 'audio/mpeg' | 'audio/ogg' | 'video/webm' | 'video/mp4' | 'text/c' | 'text/c++' | 'text/java' | 'text/rust' | 'text/go' | 'text/python' | 'text/php' | 'text/perl' | 'text/ruby' | 'text/swift' | 'text/kotlin' | 'text/scala' | 'text/javascript' | 'text/typescript' | 'text/html' | 'text/css' | 'text/csv' | 'text/xml' | 'text/yaml' | 'text/toml' | 'text/sql' | 'application/json' | 'application/jsonl' | 'application/pdf' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'application/vnd.openxmlformats-officedocument.presentationml.presentation' | 'application/msword' | 'application/vnd.ms-excel' | 'application/vnd.ms-powerpoint' | 'application/rtf' | 'application/vnd.oasis.opendocument.text' | 'sec-gemini/graph' | 'sec-gemini/timeline' | 'sec-gemini/table' | 'sec-gemini/image' | 'sec-gemini/code' | 'sec-gemini/markdown' | 'sec-gemini/json' | 'sec-gemini/html' | 'sec-gemini/canvas' — Completion type
    - `status_code` integer — The status code of the message. 2xx is Okay, 4xx is a client error, 5xx is a server error.
    - `status_message` string — Explain status code reason.
    - `usage` UsageInput — Tracks token usage for a chat completion request and response.
      - `prompt_tokens` integer — Number of tokens in the prompt
      - `generated_tokens` integer — Number of tokens used during generation
      - `total_tokens` integer — Total number of tokens used in the request (prompt + generation)
      - `cached_token_count` integer — Number of tokens used in the cached response
      - `thoughts_token_count` integer — Number of tokens used in the thoughts
      - `tool_use_prompt_token_count` integer — Number of tokens used in the tool use prompt
      - `prompt_tokens_details` ModalityTokenCount[], nullable
        - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — Server content modalities.
        - `tokenCount` integer, nullable — Number of tokens.
  - `usage` UsageInput — Tracks token usage for a chat completion request and response.
    - `prompt_tokens` integer — Number of tokens in the prompt
    - `generated_tokens` integer — Number of tokens used during generation
    - `total_tokens` integer — Total number of tokens used in the request (prompt + generation)
    - `cached_token_count` integer — Number of tokens used in the cached response
    - `thoughts_token_count` integer — Number of tokens used in the thoughts
    - `tool_use_prompt_token_count` integer — Number of tokens used in the tool use prompt
    - `prompt_tokens_details` ModalityTokenCount[], nullable
      - `modality` 'MODALITY_UNSPECIFIED' | 'TEXT' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT' — Server content modalities.
      - `tokenCount` integer, nullable — Number of tokens.
  - `can_log` boolean — Whether the session can be logged or not.
  - `state` 'undefined' | 'start' | 'end' | 'query' | 'running_agent' | 'agent_done' | 'coding' | 'code_result' | 'calling_tool' | 'tool_result' | 'generating' | 'answering' | 'thinking' | 'planning' | 'reviewing' | 'understanding' | 'retrieving' | 'grounding'
  - `files` PublicSessionFile[] — The list of files uploaded to the session.
    - `name` string, required — Name of the file.
    - `size` integer, required — Size of the file in bytes.
    - `sha256` string, required — SHA256 of the file.
    - `mime_type` string, required — Mime type.
    - `content_type_label` string, nullable — Content type label.

## Response `200`

Successful Response

- OpResult
  - `ok` boolean, required — True if the operation was successful.
  - `status_code` 200 | 201 | 202 | 204 | 206 | 300 | 301 | 302 | 303 | 304 | 307 | 308 | 400 | 401 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 422 | 425 | 426 | 428 | 429 | 429 | 431 | 451 | 500 | 500 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, required
  - `status_message` string — Describe why the operation failed.
  - `data` object, nullable — Optional field for additional information.
  - `mime_type` 'text/plain' | 'text/markdown' | 'text/serialized-json' | 'application/octet-stream' | 'image/jpeg' | 'image/png' | 'image/tiff' | 'image/gif' | 'image/svg+xml' | 'image/webp' | 'image/avif' | 'audio/wav' | 'audio/mpeg' | 'audio/ogg' | 'video/webm' | 'video/mp4' | 'text/c' | 'text/c++' | 'text/java' | 'text/rust' | 'text/go' | 'text/python' | 'text/php' | 'text/perl' | 'text/ruby' | 'text/swift' | 'text/kotlin' | 'text/scala' | 'text/javascript' | 'text/typescript' | 'text/html' | 'text/css' | 'text/csv' | 'text/xml' | 'text/yaml' | 'text/toml' | 'text/sql' | 'application/json' | 'application/jsonl' | 'application/pdf' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'application/vnd.openxmlformats-officedocument.presentationml.presentation' | 'application/msword' | 'application/vnd.ms-excel' | 'application/vnd.ms-powerpoint' | 'application/rtf' | 'application/vnd.oasis.opendocument.text' | 'sec-gemini/graph' | 'sec-gemini/timeline' | 'sec-gemini/table' | 'sec-gemini/image' | 'sec-gemini/code' | 'sec-gemini/markdown' | 'sec-gemini/json' | 'sec-gemini/html' | 'sec-gemini/canvas' — Completion type
  - `latency` number, nullable — The time taken to complete the request in seconds.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/google/apis/sec-gemini.md) · [All operations](https://skmtc.net/google/apis/sec-gemini/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/sec-gemini/versions/cc76ee2bed1c/schema)