Socket

Socket Repos API

Manage the repositories Socket is monitoring inside an organization, plus repo labels for policy targeting. CRUD repos, attach/detach labels, and configure per-label settings that override organization-level security and license policies.

Socket Repos API is one of 15 APIs that Socket publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 2 machine-runnable capabilities that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include Repositories, Labels, and Organization. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 2 Naftiko capability specs.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.socket.dev/reference/getorgrepolist

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-repos-api-openapi.yml

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/capabilities/repos-repos.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/capabilities/repos-repo-labels.yaml

OpenAPI Specification

socket-repos-api-openapi.yml Raw ↑ 
openapi: 3.0.0
info:
  description: Socket repos API endpoints.
  title: Socket Repos API
  version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
  /orgs/{org_slug}/repos:
    get:
      tags:
      - repos
      summary: List repositories
      operationId: getOrgRepoList
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: ''
        schema:
          type: string
          default: created_at
      - name: direction
        in: query
        required: false
        description: ''
        schema:
          type: string
          default: desc
      - name: per_page
        in: query
        required: false
        description: ''
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
      - name: page
        in: query
        required: false
        description: ''
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: include_archived
        in: query
        required: false
        description: Include archived repositories in the results
        schema:
          type: boolean
          default: false
      - name: workspace
        in: query
        required: false
        description: Filter repositories by workspace. When provided (including empty string), only repos in that workspace are returned.
        schema:
          type: string
      security:
      - bearerAuth:
        - repo:list
      - basicAuth:
        - repo:list
      description: 'Lists repositories for the specified organization.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - repo:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          description: The ID of the repository
                          default: ''
                        created_at:
                          type: string
                          description: The creation date of the repository
                          default: ''
                        updated_at:
                          type: string
                          description: The last update date of the repository
                          default: ''
                        html_url:
                          type: string
                          description: The URL to the repository dashboard page
                          default: ''
                        head_full_scan_id:
                          type: string
                          description: The ID of the head full scan of the repository
                          default: ''
                          nullable: true
                        integration_meta:
                          anyOf:
                          - type: object
                            additionalProperties: false
                            properties:
                              type:
                                type: string
                                enum:
                                - github
                              value:
                                type: object
                                additionalProperties: false
                                description: ''
                                properties:
                                  installation_id:
                                    type: string
                                    description: The GitHub installation_id of the active associated Socket GitHub App
                                    default: ''
                                  installation_login:
                                    type: string
                                    description: The GitHub login name that the active Socket GitHub App installation is installed to
                                    default: ''
                                  repo_name:
                                    type: string
                                    description: The name of the associated GitHub repo.
                                    default: ''
                                    nullable: true
                                  repo_id:
                                    type: string
                                    description: The id of the associated GitHub repo.
                                    default: ''
                                    nullable: true
                                required:
                                - installation_id
                                - installation_login
                                - repo_id
                                - repo_name
                          nullable: true
                        slug:
                          type: string
                          description: The slug of the repository.
                          default: ''
                        name:
                          type: string
                          description: The name of the repository
                          default: ''
                        description:
                          type: string
                          description: The description of the repository
                          default: ''
                          nullable: true
                        homepage:
                          type: string
                          description: The homepage URL of the repository
                          default: ''
                          nullable: true
                        visibility:
                          type: string
                          enum:
                          - public
                          - private
                          description: The visibility of the repository
                          default: private
                        archived:
                          type: boolean
                          default: false
                          description: Whether the repository is archived or not
                        default_branch:
                          type: string
                          description: The default branch of the repository
                          default: main
                          nullable: true
                        workspace:
                          type: string
                          description: The workspace of the repository
                          default: ''
                      description: ''
                    description: ''
                  nextPage:
                    type: integer
                    description: ''
                    default: 0
                    nullable: true
                required:
                - nextPage
                - results
          description: Lists repositories for the specified organization. The authenticated user must be a member of the organization.
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
    post:
      tags:
      - repos
      summary: Create repository
      operationId: createOrgRepo
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: on_duplicate
        in: query
        required: false
        description: Set to "redirect" to receive a 302 redirect to the existing repo instead of a 409 error when a duplicate slug is detected.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: The display name of the repository. When provided without a slug, the slug is automatically derived from the name. When omitted, the slug is used as the name. At least one
                    of name or slug must be provided.
                  default: ''
                description:
                  type: string
                  description: The description of the repository
                  default: ''
                  nullable: true
                homepage:
                  type: string
                  description: The homepage URL of the repository
                  default: ''
                  nullable: true
                visibility:
                  type: string
                  enum:
                  - public
                  - private
                  description: The visibility of the repository
                  default: private
                archived:
                  type: boolean
                  default: false
                  description: Whether the repository is archived or not
                default_branch:
                  type: string
                  description: The default branch of the repository
                  default: main
                  nullable: true
                workspace:
                  type: string
                  description: The workspace of the repository
                  default: ''
                slug:
                  type: string
                  description: The slug of the repository. If provided, used directly instead of being derived from name. Must only contain ASCII letters, digits, and the characters ., -, and _.
                  default: ''
              description: ''
        required: false
      security:
      - bearerAuth:
        - repo:create
      - basicAuth:
        - repo:create
      description: 'Create a repository.


        Repos collect Full scans and Diff scans and are typically associated with a git repo.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - repo:create'
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id:
                    type: string
                    description: The ID of the repository
                    default: ''
                  created_at:
                    type: string
                    description: The creation date of the repository
                    default: ''
                  updated_at:
                    type: string
                    description: The last update date of the repository
                    default: ''
                  html_url:
                    type: string
                    description: The URL to the repository dashboard page
                    default: ''
                  head_full_scan_id:
                    type: string
                    description: The ID of the head full scan of the repository
                    default: ''
                    nullable: true
                  integration_meta:
                    anyOf:
                    - type: object
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - github
                        value:
                          type: object
                          additionalProperties: false
                          description: ''
                          properties:
                            installation_id:
                              type: string
                              description: The GitHub installation_id of the active associated Socket GitHub App
                              default: ''
                            installation_login:
                              type: string
                              description: The GitHub login name that the active Socket GitHub App installation is installed to
                              default: ''
                            repo_name:
                              type: string
                              description: The name of the associated GitHub repo.
                              default: ''
                              nullable: true
                            repo_id:
                              type: string
                              description: The id of the associated GitHub repo.
                              default: ''
                              nullable: true
                          required:
                          - installation_id
                          - installation_login
                          - repo_id
                          - repo_name
                    nullable: true
                  slug:
                    type: string
                    description: The slug of the repository.
                    default: ''
                  name:
                    type: string
                    description: The name of the repository
                    default: ''
                  description:
                    type: string
                    description: The description of the repository
                    default: ''
                    nullable: true
                  homepage:
                    type: string
                    description: The homepage URL of the repository
                    default: ''
                    nullable: true
                  visibility:
                    type: string
                    enum:
                    - public
                    - private
                    description: The visibility of the repository
                    default: private
                  archived:
                    type: boolean
                    default: false
                    description: Whether the repository is archived or not
                  default_branch:
                    type: string
                    description: The default branch of the repository
                    default: main
                    nullable: true
                  workspace:
                    type: string
                    description: The workspace of the repository
                    default: ''
                description: ''
          description: Lists repositories for the specified organization. The authenticated user must be a member of the organization.
        '302':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id:
                    type: string
                    description: The ID of the repository
                    default: ''
                  created_at:
                    type: string
                    description: The creation date of the repository
                    default: ''
                  updated_at:
                    type: string
                    description: The last update date of the repository
                    default: ''
                  html_url:
                    type: string
                    description: The URL to the repository dashboard page
                    default: ''
                  head_full_scan_id:
                    type: string
                    description: The ID of the head full scan of the repository
                    default: ''
                    nullable: true
                  integration_meta:
                    anyOf:
                    - type: object
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - github
                        value:
                          type: object
                          additionalProperties: false
                          description: ''
                          properties:
                            installation_id:
                              type: string
                              description: The GitHub installation_id of the active associated Socket GitHub App
                              default: ''
                            installation_login:
                              type: string
                              description: The GitHub login name that the active Socket GitHub App installation is installed to
                              default: ''
                            repo_name:
                              type: string
                              description: The name of the associated GitHub repo.
                              default: ''
                              nullable: true
                            repo_id:
                              type: string
                              description: The id of the associated GitHub repo.
                              default: ''
                              nullable: true
                          required:
                          - installation_id
                          - installation_login
                          - repo_id
                          - repo_name
                    nullable: true
                  slug:
                    type: string
                    description: The slug of the repository.
                    default: ''
                  name:
                    type: string
                    description: The name of the repository
                    default: ''
                  description:
                    type: string
                    description: The description of the repository
                    default: ''
                    nullable: true
                  homepage:
                    type: string
                    description: The homepage URL of the repository
                    default: ''
                    nullable: true
                  visibility:
                    type: string
                    enum:
                    - public
                    - private
                    description: The visibility of the repository
                    default: private
                  archived:
                    type: boolean
                    default: false
                    description: Whether the repository is archived or not
                  default_branch:
                    type: string
                    description: The default branch of the repository
                    default: main
                    nullable: true
                  workspace:
                    type: string
                    description: The workspace of the repository
                    default: ''
                description: ''
          description: Redirects to the existing repository when on_duplicate=redirect is set and a duplicate slug is detected.
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '409':
          $ref: '#/components/responses/SocketConflict'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
  /orgs/{org_slug}/repos/{repo_slug}:
    get:
      tags:
      - repos
      summary: Get repository
      operationId: getOrgRepo
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: repo_slug
        in: path
        required: true
        description: The slug of the repository
        schema:
          type: string
      - name: workspace
        in: query
        required: false
        description: The workspace of the repository
        schema:
          type: string
      security:
      - bearerAuth:
        - repo:list
      - basicAuth:
        - repo:list
      description: 'Retrieve a repository associated with an organization.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - repo:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  id:
                    type: string
                    description: The ID of the repository
                    default: ''
                  created_at:
                    type: string
                    description: The creation date of the repository
                    default: ''
                  updated_at:
                    type: string
                    description: The last update date of the repository
                    default: ''
                  html_url:
                    type: string
                    description: The URL to the repository dashboard page
                    default: ''
                  head_full_scan_id:
                    type: string
                    description: The ID of the head full scan of the repository
                    default: ''
                    nullable: true
                  integration_meta:
                    anyOf:
                    - type: object
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - github
                        value:
                          type: object
                          additionalProperties: false
                          description: ''
                          properties:
                            installation_id:
                              type: string
                              description: The GitHub installation_id of the active associated Socket GitHub App
                              default: ''
                            installation_login:
                              type: string
                              description: The GitHub login name that the active Socket GitHub App installation is installed to
                              default: ''
                            repo_name:
                              type: string
                              description: The name of the associated GitHub repo.
                              default: ''
                              nullable: true
                            repo_id:
                              type: string
                              description: The id of the associated GitHub repo.
                              default: ''
                              nullable: true
                          required:
                          - installation_id
                          - installation_login
                          - repo_id
                          - repo_name
                    nullable: true
                  slug:
                    type: string
                    description: The slug of the repository.
                    default: ''
                  name:
                    type: string
                    description: The name of the repository
                    default: ''
                  description:
                    type: string
                    description: The description of the repository
                    default: ''
                    nullable: true
                  homepage:
                    type: string
                    description: The homepage URL of the repository
                    default: ''
                    nullable: true
                  visibility:
                    type: string
                    enum:
                    - public
                    - private
                    description: The visibility of the repository
                    default: private
                  archived:
                    type: boolean
                    default: false
                    description: Whether the repository is archived or not
                  default_branch:
                    type: string
                    description: The default branch of the repository
                    default: main
                    nullable: true
                  workspace:
                    type: string
                    description: The workspace of the repository
                    default: ''
                  slig:
                    type: string
                    description: The slug of the repository. This typo is intentionally preserved for backwards compatibility reasons.
                    default: ''
                required:
                - archived
                - created_at
                - default_branch
                - description
                - head_full_scan_id
                - homepage
                - html_url
                - id
                - integration_meta
                - name
                - slig
                - slug
                - updated_at
                - visibility
                - workspace
          description: Lists repositories for the specified organization. The authenticated user must be a member of the organization.
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
    post:
      tags:
      - repos
      summary: Update repository
      operationId: updateOrgRepo
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: repo_slug
        in: path
        required: true
        description: The slug of the repository
        schema:
          type: string
      - name: workspace
        in: query
        required: false
        description: The workspace of the repository
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: The name of the repository
                  default: ''
                description:
                  type: string
                  description: The description of the repository
                  default: ''
                  nullable: true
                homepage:
                  type: string
                  description: The homepage URL of the repository
                  default: ''
                  nullable: true
                visibility:
                  type: string
                  enum:
                  - public
                  - private
                  description: The visibility of the repository
                  default: private
                archived:
                  type: boolean
                  default: false
                  description: Whether the repository is archived or not
                default_branch:
                  type: string
                  description: The default branch of the repository
                  default: main
                  nullable: true
                workspace:
                  type: string
                  description: The workspace of the repository
                  default: ''
              description: ''
        required: false
      security:
      - bearerAuth:
        - repo:update
      - basicAuth:
        - repo:update
      description: 'Update details of an existing repository.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - repo:update'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id:
                    type: string
                    description: The ID of the repository
                    default: ''
                  created_at:
                    type: string
                    description: The creation date of the repository
                    default: ''
                  updated_at:
                    type: string
                    description: The last update date of the repository
                    default: ''
                  html_url:
                    type: string
                    description: The URL to the repository dashboard page
                    default: ''
                  head_full_scan_id:
                    type: string
                    description: The ID of the head full scan of the repository
                    default: ''
                    nullable: true
                  integration_meta:
                    anyOf:
                    - type: object
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - github
                        value:
                          type: object
                          additionalProperties: false
                          description: ''
                          properties:
                            installation_id:
                              type: string
                              description: The GitHub installation_id of the active associated Socket GitHub App
                              default: ''
                            installation_login:
                              type: string
                              description: The GitHub login name that the active Socket GitHub App installation is installed to
                              default: ''
                            repo_name:
                              type: string
                              description: The name of the associated GitHub repo.
                              default: ''
                              nullable: true
                            repo_id:
                              type: string
                              description: The id of the associated GitHub repo.
                              default: ''
                              nullable: true
                          required:
                          - installation_id
                          - installation_login
                          - repo_id
                          - repo_name
                    nullable: true
                  slug:
                    type: string
                    description: The slug of the repository.
                    default: ''
                  name:
                    type: string
                    description: The name of the repository
                    default: ''
                  description:
                    type: string
                    description: The description of the repository
                    default: ''
                    nullable: true
                  homepage:
                    type: string
                    description: The homepage URL of the repository
                    default: ''
                    nullable: true
                  visibility:
                    type: string
                    enum:
                    - public
                    - private
                    description: The visibility of the repository
                    default: private
          

# --- truncated at 32 KB (237 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-repos-api-openapi.yml