> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mka1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve a conversation permission

> Returns the role a principal effectively holds on the conversation and where it comes from: `owner`, a permission granted to it (`grant`), the conversation's `team` permission, or `none`. A principal with `none` can still reach the conversation as an organization admin of its team; that is decided per request from the caller's role. Only the conversation's owner or an organization admin of its team can retrieve another principal's permission (403 otherwise). Any caller who can read the conversation can retrieve its own, by passing the id its requests are known by: the `X-On-Behalf-Of` end-user id when the request carries one, else its user id. For a caller who is neither the owner nor an organization admin that answer is `reader` or `writer`, which is how it learns whether it may write.



## OpenAPI

````yaml https://apigw.mka1.com/speakeasy.json get /api/v1/llm/conversations/{conversation_id}/permissions/{user_id}
openapi: 3.1.1
info:
  title: MKA1 API
  version: 1.1.0
  description: >-
    The MKA1 API is a RESTful API that provides access to the MKA1 platform.
    Learn how to get started with the API and the TypeScript SDK
    [here](https://mka1.apidocumentation.com/guides/getting-started).
  license:
    name: Proprietary
servers:
  - url: https://apigw.mka1.com
    description: MKA1 API Gateway
  - url: /
    description: Relative server URL (configurable via SDK constructor)
security: []
tags:
  - name: Audit
    description: >-
      Audit API for org owners and admins. Trace one request end to end by its
      X-Request-ID: API gateway timing, the responses it created, and their
      model invocations and tool calls.
    x-displayName: Audit
  - name: Embeddings
    description: >-
      Text embedding API endpoints for generating vector representations of
      text. Create semantic embeddings for search, clustering, and similarity
      matching using various embedding models.
    x-displayName: Embeddings
  - name: Feedback
    description: >-
      User feedback API for rating and commenting on chat completions. Collect
      thumbs up/down ratings and detailed feedback to improve model responses
      and track user satisfaction.
    x-displayName: Feedback
  - name: Images
    description: >-
      Image generation API endpoints for creating images from text descriptions.
      Generate images with control over size, quality, and style.
    x-displayName: Images
  - name: MCP Vault
    description: >-
      MCP vault API for storing user-owned MCP server configurations and
      encrypted credentials. Agents reference vault IDs so secrets are resolved
      only at tool execution time.
    x-displayName: MCP Vault
  - name: Speech
    description: >-
      Speech API endpoints for audio processing. Convert text to
      natural-sounding speech (TTS) or transcribe speech to text (STT) in
      different languages.
    x-displayName: Speech
  - name: Usage
    description: >-
      Usage tracking and analytics API for monitoring token consumption, request
      counts, and cost analysis. View detailed statistics per user, model, and
      time period.
    x-displayName: Usage
  - name: Extract
    description: >-
      Structured data extraction API for extracting information from files.
      Define JSON schemas to extract structured data from images, PDFs, and
      documents. Supports reusable schema templates.
    x-displayName: Extract
  - name: Text Classification
    description: >-
      Text classification API for categorizing text into predefined labels. Use
      AI models to classify text content for sentiment analysis, topic
      categorization, and content moderation.
    x-displayName: Text Classification
  - name: Responses
    description: >-
      Agent-powered responses API for creating AI agents with autonomous tool
      usage. Build conversational assistants that can use web search, file
      operations, image generation, code execution, and MCP integrations.
      Supports background processing, streaming, and real-time status tracking.
    x-displayName: Responses
  - name: Files
    description: >-
      File management API for uploading, storing, and managing files with
      automatic expiration and S3 integration. Upload files that can be used
      with Assistants, Vector Stores, and other features. Files are stored in S3
      with metadata tracked in PostgreSQL. Supports automatic cleanup of expired
      files.
    x-displayName: Files
  - name: Vector Stores
    description: >-
      Vector store API for storing and searching documents using embeddings.
      Create vector stores, upload files with automatic chunking and embedding
      generation, and perform semantic search. Files are processed
      asynchronously using Temporal workflows for durability. Supports automatic
      cleanup of expired stores and LanceDB for efficient vector storage.
    x-displayName: Vector Stores
  - name: Conversations
    description: >-
      Conversation management API for storing and retrieving conversation state
      across Response API calls. Create conversations, add items (user messages,
      assistant messages, system messages), and maintain conversation history.
      Supports metadata tracking and multi-turn dialogue state management.
    x-displayName: Conversations
  - name: Guardrails
    description: >-
      AI safety guardrails API for configuring content moderation and security
      policies. Set up ban word lists, prompt injection detection, and system
      prompt leakage prevention. Guardrails apply to all requests from an
      account and can be tested before deployment.
    x-displayName: Guardrails
  - name: Tool Policy
    description: >-
      Organization tool policy API. Org admins deny tool types, or require
      approval before their calls run, for every Responses request in the
      organization, including saved agent runs. The policy overrides what
      requests and agents configure.
    x-displayName: Tool Policy
  - name: Models
    description: >-
      Model listing API for discovering available models. Returns model IDs,
      ownership, and metadata for all registered models in the gateway.
    x-displayName: Models
  - name: Skills
    description: >-
      Skills API for managing versioned bundles of instructions and files
      following the Agent Skills standard. Create, version, and download
      reusable skill packages that include SKILL.md manifests for agent
      environments.
    x-displayName: Skills
  - name: Chat Completions
    description: >-
      **Deprecated: Use the Responses API (`/api/v1/llm/responses`) instead.**
      Chat completion endpoints with support for streaming, tool calls, and
      multiple providers.
    x-deprecated: true
    x-displayName: Chat Completions
  - name: Batches
    x-displayName: Batches
  - name: Evals
    x-displayName: Evals
  - name: Fine-Tuning
    x-displayName: Fine-Tuning
  - name: Memory Stores
    x-displayName: Memory Stores
  - name: Prompts
    x-displayName: Prompts
  - name: API Key
    x-displayName: API Key
  - name: OAuth
    x-displayName: OAuth
  - name: Session
    x-displayName: Session
  - name: Organization
    x-displayName: Organization
  - name: Cluster Admin
    x-displayName: Cluster Admin
  - name: Sessions
    description: Create, inspect, access, and terminate sandbox sessions.
    x-displayName: Sessions
  - name: Browser
    description: >-
      Connect to browser sessions through the gateway port proxy. Browser
      sessions expose a Chrome DevTools Protocol endpoint on port 9222.
    x-displayName: Browser
  - name: Execution
    description: Run shell commands and code inside an existing sandbox session.
    x-displayName: Execution
  - name: Workspace
    description: >-
      Inspect the workspace manifest, transfer files or archives, and download
      generated artifacts.
    x-displayName: Workspace
  - name: Sandbox Usage
    description: >-
      Aggregate sandbox usage statistics across sessions, execution, and
      workspace operations.
    x-displayName: Sandbox Usage
  - name: Sandbox Pricing
    description: >-
      Cluster-admin management of the sandbox compute rate card used for
      budgeted spend.
    x-displayName: Sandbox Pricing
  - name: Sandbox GitHub
    description: >-
      Connect a GitHub account, clone its repositories into sandbox sessions,
      and push branches and open pull requests from a session. The GitHub token
      stays in the sandbox service and never enters a session.
    x-displayName: Sandbox GitHub
  - name: Sandbox Environments
    description: >-
      Save reusable session configuration (repositories, environment variables,
      network access, and a setup script) and run the setup script in a session.
    x-displayName: Sandbox Environments
  - name: Sandbox Connectors
    description: >-
      Connect remote MCP servers (Linear, Notion, Sentry and others) to your
      account so Coding Harness sessions started from an environment that lists
      them can call their tools. The sandbox service keeps each connector's
      credential and never puts it in a session.
    x-displayName: Sandbox Connectors
  - name: Agents
    description: Create and manage reusable agent definitions.
    x-displayName: Agents
  - name: Agent Versions
    description: Inspect an agent's configuration history and roll back to a prior version.
    x-displayName: Agent Versions
  - name: Agent Runs
    description: Execute saved agents and inspect persisted run results.
    x-displayName: Agent Runs
  - name: Agent Connectors
    description: >-
      Connect saved agents to external messaging channels such as Telegram,
      including text, photo, and supported document exchange.
    x-displayName: Agent Connectors
  - name: Agent Schedules
    description: Create and manage scheduled or recurring saved agent runs.
    x-displayName: Agent Schedules
  - name: schema-3_other
    x-displayName: other
  - name: Billing
    x-displayName: Billing
  - name: Budgets
    x-displayName: Budgets
  - name: Settings
    x-displayName: Settings
  - name: Compute Jobs
    x-displayName: Compute Jobs
  - name: Compute Services
    x-displayName: Compute Services
  - name: Compute Catalog
    x-displayName: Compute Catalog
  - name: Compute Volumes
    x-displayName: Compute Volumes
  - name: Compute Pricing
    x-displayName: Compute Pricing
  - name: Compute Secrets
    x-displayName: Compute Secrets
  - name: Compute Usage
    x-displayName: Compute Usage
  - name: Compute Tenants
    x-displayName: Compute Tenants
  - description: Create, list, read, update, and delete repositories.
    name: Repositories
    x-displayName: Repositories
  - name: Tracking Experiments
    description: Create and query tenant experiments.
    x-displayName: Tracking Experiments
  - name: Tracking Runs
    description: Record and retrieve run parameters, metrics, and tags.
    x-displayName: Tracking Runs
  - name: analytics.projects
    x-displayName: Projects
    description: Create, list, rename, and archive analytics projects.
  - name: analytics.keys
    x-displayName: Capture keys
    description: Create and revoke project keys for sending events.
  - name: analytics
    x-displayName: Events
    description: Send events and query event counts or unique visitors.
  - name: analytics.events
    x-displayName: Event search
    description: List individual events with their properties, newest first.
  - name: analytics.visitors
    x-displayName: Visitor search
    description: List visitors by their latest activity, with first and last seen times.
  - name: generators
    x-displayName: generators
  - name: generations
    x-displayName: generations
  - name: formats
    x-displayName: formats
  - description: >-
      Flags, environments, evaluation, and the audit log. Administrative
      operations require a cluster administrator; evaluation uses an
      environment-specific evaluation key.
    name: Feature Flags
    x-displayName: Feature Flags
  - name: Service Status
    description: >-
      Current status of each service and the incident history, for this
      deployment's region.
    x-displayName: Service Status
  - name: Support Cases
    description: >-
      Open and follow support cases. Organization owners and admins see all of
      the organization's cases; other members see the cases they opened.
    x-displayName: Support Cases
  - name: Vector Store Connectors
    description: 'Vector store connectors: external locations mirrored into vector stores.'
    x-displayName: Vector Store Connectors
paths:
  /api/v1/llm/conversations/{conversation_id}/permissions/{user_id}:
    get:
      tags:
        - Conversations
      summary: Retrieve a conversation permission
      description: >-
        Returns the role a principal effectively holds on the conversation and
        where it comes from: `owner`, a permission granted to it (`grant`), the
        conversation's `team` permission, or `none`. A principal with `none` can
        still reach the conversation as an organization admin of its team; that
        is decided per request from the caller's role. Only the conversation's
        owner or an organization admin of its team can retrieve another
        principal's permission (403 otherwise). Any caller who can read the
        conversation can retrieve its own, by passing the id its requests are
        known by: the `X-On-Behalf-Of` end-user id when the request carries one,
        else its user id. For a caller who is neither the owner nor an
        organization admin that answer is `reader` or `writer`, which is how it
        learns whether it may write.
      operationId: getConversationPermission
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            description: The ID of the conversation.
          example: conv_abc123
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            minLength: 1
            description: >-
              The principal: a member's user id, the end-user id a request is
              delegated to with X-On-Behalf-Of, or 'team' for the permission
              that applies to every member of the conversation's team.
          example: user_8f2c1
        - name: X-On-Behalf-Of
          in: header
          required: false
          schema:
            type: string
          description: Optional external end-user identifier forwarded by the API gateway.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationEffectivePermission'
              example:
                object: conversation.permission
                conversation_id: conv_abc123
                grantee_type: user
                user_id: user_8f2c1
                role: reader
                source: grant
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: python
          label: Python (SDK)
          source: |-
            from meetkai_mka1 import SDK


            with SDK(
                bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
            ) as sdk:

                res = sdk.llm.conversations.get_permission(conversation_id="conv_abc123", user_id="user_8f2c1")

                # Handle response
                print(res)
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { SDK } from "@meetkai/mka1";

            const sdk = new SDK({
              bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
            });

            async function run() {
              const result = await sdk.llm.conversations.getPermission({
                conversationId: "conv_abc123",
                userId: "user_8f2c1",
              });

              console.log(result);
            }

            run();
        - lang: go
          label: Go (SDK)
          source: "package main\n\nimport(\n\t\"context\"\n\tmka1 \"github.com/MeetKai/mka1-sdks/go\"\n\t\"log\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    s := mka1.New(\n        mka1.WithSecurity(\"<YOUR_BEARER_TOKEN_HERE>\"),\n    )\n\n    res, err := s.Llm.Conversations.GetPermission(ctx, \"conv_abc123\", \"user_8f2c1\", nil)\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.ConversationEffectivePermission != nil {\n        // handle response\n    }\n}"
        - lang: csharp
          label: CSharp (SDK)
          source: |-
            using MeetKai.MKA1;
            using MeetKai.MKA1.Types.Components;

            var sdk = new SDK(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

            var res = await sdk.Llm.Conversations.GetPermissionAsync(
                conversationId: "conv_abc123",
                userId: "user_8f2c1"
            );

            // handle response
components:
  schemas:
    ConversationEffectivePermission:
      type: object
      properties:
        object:
          const: conversation.permission
          description: The object type, which is always 'conversation.permission'.
        conversation_id:
          type: string
          description: The ID of the conversation.
        grantee_type:
          $ref: '#/components/schemas/ResourcePermissionGranteeType'
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The principal the permission applies to: a member's user id, or the
            end-user id a request is delegated to with `X-On-Behalf-Of`. `null`
            when the permission applies to the conversation's team.
        role:
          anyOf:
            - $ref: '#/components/schemas/ResourcePermissionRole'
            - type: 'null'
          description: >-
            The highest role the principal holds on the conversation, or null
            when it holds none.
        source:
          $ref: '#/components/schemas/ResourcePermissionSource'
      required:
        - object
        - conversation_id
        - grantee_type
        - user_id
        - role
        - source
      description: >-
        The effective permission of one principal on a conversation, with where
        it comes from.
    ResourcePermissionGranteeType:
      enum:
        - user
        - team
      type: string
      description: >-
        Who the permission applies to: one principal (`user`), or every member
        of the resource's team (`team`).
    ResourcePermissionRole:
      enum:
        - owner
        - writer
        - reader
      type: string
      description: >-
        The role held on the resource. `owner` is the resource's creator and
        cannot be granted; `writer` includes `reader`.
    ResourcePermissionSource:
      enum:
        - owner
        - grant
        - team
        - none
      type: string
      description: >-
        Where the role comes from: the resource's owner, a permission held by
        this principal, the resource's `team` permission, or nothing — the
        principal reaches the resource only as an org admin of its team, if at
        all.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Send Authorization: Bearer <credential>, using an MKA1 API key for
        automation or an OAuth API access token for a signed-in application. Use
        a dynamic security callback to refresh OAuth access tokens. Browser
        session-only operations still require their declared cookie.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.