Openwork GitHub API
The GitHub API from Openwork — 11 operation(s) for github.
Documentation
Documentation
https://openworklabs.com/docs
APIReference
https://openworklabs.com/docs/api-reference
OpenAPI Specification
openapi: 3.1.0
info:
title: Den Admin GitHub API
description: 'OpenAPI spec for the Den control plane API.
Authentication:
- Use `Authorization: Bearer <session-token>` for user-authenticated routes that require a Den session.
- Use `x-api-key: <den-api-key>` for API-key-authenticated routes that accept organization API keys.
- Public routes like health and documentation do not require authentication.
Swagger tip: use the security schemes in the Authorize dialog to set either `bearerAuth` or `denApiKey` before trying protected endpoints.'
version: dev
servers:
- url: https://api.openworklabs.com
tags:
- name: GitHub
paths:
/v1/connectors/github/install/start:
post:
operationId: postV1ConnectorsGithubInstallStart
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
returnPath:
type: string
minLength: 1
maxLength: 1024
required:
- returnPath
tags:
- GitHub
summary: Start GitHub install
description: Builds a GitHub App install redirect URL for the current organization.
responses:
'200':
description: GitHub install redirect returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginArchGithubInstallStartResponse'
'400':
description: The GitHub install request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to connect GitHub.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: The caller lacks permission to connect GitHub.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
/v1/connectors/github/install/complete:
post:
operationId: postV1ConnectorsGithubInstallComplete
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
installationId:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
state:
type: string
minLength: 1
maxLength: 4096
required:
- installationId
- state
tags:
- GitHub
summary: Complete GitHub install
description: Completes a GitHub App installation for the current organization and returns visible repositories.
responses:
'200':
description: GitHub installation completed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginArchGithubInstallCompleteResponse'
'400':
description: The GitHub install completion request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to complete GitHub connection.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: The caller lacks permission to complete GitHub connection.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
/v1/plugins/import-mcps-from-github-url/preview:
post:
operationId: postV1PluginsImportMcpsFromGithubUrlPreview
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
githubUrl:
type: string
maxLength: 2048
format: uri
required:
- githubUrl
tags:
- GitHub
summary: Preview GitHub plugin marketplace import
description: Reads a public GitHub plugin URL and returns skills and remote MCP servers that can be imported into an organization marketplace.
responses:
'200':
description: GitHub plugin MCP import preview returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GithubPluginMcpImportPreviewResponse'
'400':
description: The GitHub plugin MCP import preview request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to preview plugin MCP imports.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'404':
description: The GitHub plugin path could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
/v1/plugins/import-mcps-from-github-url:
post:
operationId: postV1PluginsImportMcpsFromGithubUrl
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
githubUrl:
type: string
maxLength: 2048
format: uri
access:
type: object
properties:
orgWide:
default: true
type: boolean
memberIds:
maxItems: 200
type: array
items:
description: Den TypeID with 'om_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 29
maxLength: 29
pattern: ^om_.*
teamIds:
maxItems: 200
type: array
items:
description: Den TypeID with 'tem_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^tem_.*
authType:
default: oauth
type: string
enum:
- oauth
- none
credentialMode:
default: per_member
type: string
enum:
- shared
- per_member
description:
anyOf:
- type: string
maxLength: 65535
- type: 'null'
marketplaceId:
description: Den TypeID with 'mkt_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^mkt_.*
name:
type: string
minLength: 1
maxLength: 255
selectedSkillKeys:
maxItems: 200
type: array
items:
type: string
minLength: 1
maxLength: 1024
selectedServerKeys:
maxItems: 200
type: array
items:
type: string
minLength: 1
maxLength: 1024
selectedServerNames:
maxItems: 200
type: array
items:
type: string
minLength: 1
maxLength: 255
required:
- githubUrl
tags:
- GitHub
summary: Create a plugin from GitHub
description: Creates one plugin from selected skills and remote MCP servers in a public GitHub plugin URL, applies the requested access grants, and optionally publishes it into an organization marketplace. Declared and known-server authentication requirements take precedence over the request-wide auth fallback.
responses:
'200':
description: GitHub plugin MCPs imported successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GithubPluginMcpImportResponse'
'400':
description: The GitHub plugin MCP import request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to import plugin MCPs.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: The caller lacks permission to import plugin MCPs.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: The GitHub plugin path or marketplace could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
/v1/connector-instances/{connectorInstanceId}/discovery:
get:
operationId: getV1ConnectorInstancesByConnectorInstanceIdDiscovery
parameters:
- in: path
name: connectorInstanceId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^cin_.*
required: true
description: Den TypeID with 'cin_' prefix and a 26-character base32 suffix.
tags:
- GitHub
summary: Get GitHub connector discovery
description: Analyzes a GitHub connector target and returns discovered plugin candidates.
responses:
'200':
description: GitHub connector discovery returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginArchGithubConnectorDiscoveryResponse'
'400':
description: The connector instance path parameters were invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to inspect GitHub discovery.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'404':
description: The connector instance could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
/v1/connector-instances/{connectorInstanceId}/discovery/tree:
get:
operationId: getV1ConnectorInstancesByConnectorInstanceIdDiscoveryTree
parameters:
- in: path
name: connectorInstanceId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^cin_.*
required: true
description: Den TypeID with 'cin_' prefix and a 26-character base32 suffix.
- in: query
name: cursor
schema:
type: string
minLength: 1
maxLength: 255
- in: query
name: limit
schema:
type: integer
exclusiveMinimum: 0
maximum: 500
- in: query
name: prefix
schema:
type: string
minLength: 1
maxLength: 1024
tags:
- GitHub
summary: List GitHub discovery tree entries
description: Pages through the normalized GitHub repository tree used during discovery.
responses:
'200':
description: GitHub discovery tree returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginArchGithubDiscoveryTreeResponse'
'400':
description: The discovery tree request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to inspect GitHub discovery tree entries.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'404':
description: The connector instance could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
/v1/connector-instances/{connectorInstanceId}/discovery/apply:
post:
operationId: postV1ConnectorInstancesByConnectorInstanceIdDiscoveryApply
parameters:
- in: path
name: connectorInstanceId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^cin_.*
required: true
description: Den TypeID with 'cin_' prefix and a 26-character base32 suffix.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
autoImportNewPlugins:
default: false
type: boolean
selectedKeys:
maxItems: 200
type: array
items:
type: string
minLength: 1
maxLength: 255
required:
- selectedKeys
tags:
- GitHub
summary: Apply GitHub discovery selection
description: Creates OpenWork plugins and connector mappings from selected discovery candidates.
responses:
'200':
description: GitHub discovery selection applied successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginArchGithubDiscoveryApplyResponse'
'400':
description: The discovery apply request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to apply discovery selections.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: The caller lacks permission to edit this connector instance.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: The connector instance could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
/v1/connectors/github/accounts:
post:
operationId: postV1ConnectorsGithubAccounts
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
installationId:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
accountLogin:
type: string
minLength: 1
maxLength: 255
accountType:
type: string
enum:
- Organization
- User
displayName:
type: string
minLength: 1
maxLength: 255
required:
- installationId
- accountLogin
- accountType
- displayName
tags:
- GitHub
summary: Create GitHub connector account
description: Persists one GitHub App installation as a connector account.
responses:
'201':
description: GitHub connector account created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginArchConnectorAccountMutationResponse'
'400':
description: The GitHub account creation request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to create GitHub connector accounts.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: The caller lacks permission to create GitHub connector accounts.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
/v1/connectors/github/setup:
post:
operationId: postV1ConnectorsGithubSetup
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
installationId:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
connectorAccountId:
description: Den TypeID with 'cac_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^cac_.*
connectorInstanceName:
type: string
minLength: 1
maxLength: 255
repositoryId:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
repositoryFullName:
type: string
minLength: 1
maxLength: 255
branch:
type: string
minLength: 1
maxLength: 255
ref:
type: string
minLength: 1
maxLength: 255
mappings:
maxItems: 100
type: array
items:
type: object
properties:
mappingKind:
type: string
enum:
- path
- api
- custom
selector:
type: string
minLength: 1
maxLength: 255
objectType:
type: string
enum:
- skill
- agent
- command
- tool
- mcp
- hook
- context
- custom
pluginId:
anyOf:
- description: Den TypeID with 'plg_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^plg_.*
- type: 'null'
autoAddToPlugin:
default: false
type: boolean
config:
type: object
properties: {}
additionalProperties: {}
required:
- mappingKind
- selector
- objectType
required:
- installationId
- connectorInstanceName
- repositoryId
- repositoryFullName
- branch
- ref
tags:
- GitHub
summary: Setup GitHub connector
description: Creates a GitHub connector account, instance, target, and initial mappings in one flow.
responses:
'201':
description: GitHub connector setup created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginArchGithubSetupResponse'
'400':
description: The GitHub setup request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to setup GitHub connectors.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: The caller lacks permission to setup GitHub connectors.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
/v1/connectors/github/accounts/{connectorAccountId}/repositories:
get:
operationId: getV1ConnectorsGithubAccountsByConnectorAccountIdRepositories
parameters:
- in: path
name: connectorAccountId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^cac_.*
required: true
description: Den TypeID with 'cac_' prefix and a 26-character base32 suffix.
- in: query
name: cursor
schema:
type: string
minLength: 1
maxLength: 255
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
- in: query
name: q
schema:
type: string
minLength: 1
maxLength: 255
tags:
- GitHub
summary: List GitHub repositories
description: Lists repositories visible to one GitHub connector account.
responses:
'200':
description: GitHub repositories returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginArchGithubRepositoryListResponse'
'400':
description: The GitHub repository query parameters were invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to list GitHub repositories.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'404':
description: The connector account could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
/v1/connectors/github/validate-target:
post:
operationId: postV1ConnectorsGithubValidateTarget
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
installationId:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
repositoryId:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
repositoryFullName:
type: string
minLength: 1
maxLength: 255
branch:
type: string
minLength: 1
maxLength: 255
ref:
type: string
minLength: 1
maxLength: 255
required:
- installationId
- repositoryId
- repositoryFullName
- branch
- ref
tags:
- GitHub
summary: Validate GitHub target
description: Validates one repository-branch target before persisting it.
responses:
'200':
description: GitHub target validated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PluginArchGithubValidateTargetResponse'
'400':
description: The GitHub target validation request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in to validate GitHub targets.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
components:
schemas:
PluginArchConnectorAccount:
type: object
properties:
id:
description: Den TypeID with 'cac_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^cac_.*
organizationId:
description: Den TypeID with 'org_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^org_.*
connectorType:
type: string
enum:
- github
remoteId:
type: string
minLength: 1
maxLength: 255
externalAccountRef:
anyOf:
- type: string
minLength: 1
maxLength: 255
- type: 'null'
displayName:
type: string
minLength: 1
maxLength: 255
status:
type: string
enum:
- active
- inactive
- disconnected
- error
createdByName:
anyOf:
- type: string
minLength: 1
maxLength: 255
- type: 'null'
createdByOrgMembershipId:
description: Den TypeID with 'om_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 29
maxLength: 29
pattern: ^om_.*
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updatedAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
metadata:
type: object
properties: {}
additionalProperties: {}
required:
- id
- organizationId
- connectorType
- remoteId
- externalAccountRef
- displayName
- status
- createdByOrgMembershipId
- createdAt
- updatedAt
PluginArchGithubConnectorDiscoveryResponse:
type: object
properties:
ok:
type: boolean
const: true
item:
type: object
properties:
autoImportNewPlugins:
type: boolean
classification:
type: string
enum:
- claude_marketplace_repo
- claude_multi_plugin_repo
- claude_single_plugin_repo
- folder_inferred_repo
- unsupported
connectorInstance:
$ref: '#/components/schemas/PluginArchConnectorInstance'
connectorTarget:
$ref: '#/components/schemas/PluginArchConnectorTarget'
discoveredPlugins:
type: array
items:
$ref: '#/components/schemas/PluginArchGithubDiscoveredPlugin'
repositoryFullName:
type: string
minLength: 1
sourceRevisionRef:
type: string
minLength: 1
steps:
type: array
items:
$ref: '#/components/schemas/PluginArchGithubDiscoveryStep'
treeSummary:
$ref: '#/components/schemas/PluginArchGithubDiscoveryTreeSummary'
warnings:
type: array
items:
type: string
minLength: 1
required:
- autoImportNewPlugins
- classification
- connectorInstance
- connectorTarget
- discoveredPlugins
- repositoryFullName
- sourceRevisionRef
- steps
- treeSummary
- warnings
required:
- ok
- item
PluginArchMarketplace:
type: object
properties:
id:
description: Den TypeID with 'mkt_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^mkt_.*
organizationId:
description: Den TypeID with 'org_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^org_.*
name:
type: string
minLength: 1
maxLength: 255
description:
anyOf:
- type: string
minLength: 1
- type: 'null'
logoUrl:
anyOf:
- type: string
minLength: 1
- type: 'null'
status:
type: string
enum:
- active
- inactive
- deleted
- archived
createdByOrgMembershipId:
description: Den TypeID with 'om_' prefix and a 26-character base32 suffix.
format: typeid
type: string
minLength: 29
maxLength: 29
pattern: ^om_.*
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
updatedAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
deletedAt:
anyOf:
- type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openwork/refs/heads/main/openapi/openwork-github-api-openapi.yml