DocsSkmtc API

This reference is the skmtc/skmtc-api API on Hub. Star it to see each revision, and add a pipeline to get its changes.

Star
POST

Publish an API from a URL

Changed on Nov 2, 2026

Publish an API from a schema document at a URL, as importApi does, with the publish:schemas scope. The document is fetched, validated, content-addressed and deduplicated. Re-importing a URL the owner already imported adds a revision to that API. Visibility is mandatory.

Request

Method
POST
Path
/v1/apis/publish/import
content-type
application/json

Request body

object

Request body for publishing an API from a schema document at a URL.

urlstringrequired

A URL to an OpenAPI / Swagger document - raw, a GitHub blob or a GitLab blob.

ownerstring

Handle of the account that will own the API - the caller, or an organization the caller is a member of. Defaults to the caller.

slugstring

URL slug for the new API within the owner's namespace. Omit to derive one from the document's info.title. Ignored when the URL extends an API the owner has already imported.

visibilityenumrequiredpublicprivate

Visibility for a newly created API.

Example request
{
  "url": "string",
  "owner": "string",
  "slug": "string",
  "visibility": "public"
}

Response

201 application/json

The request has succeeded and a new resource has been created as a result.

object

The outcome of importing a schema document into the catalog.

apiobjectrequired

The API the schema belongs to - newly created, or extended with a revision.

revisionobjectrequired

The revision created - or the pre-existing one when deduped is true.

dedupedbooleanrequired

True when identical content already existed; no new revision was created.

isNewApibooleanrequired

True when the import created a brand-new API entry.

docsUrlstringrequired

The absolute URL of the API's docs page.

diffsPendingbooleanrequired

True when the API's full revision history is still being archived + diffed in the background - a large GitHub history deferred to the diff-backfill queue so the import responds without waiting on minutes of container diffs. The returned revision (the newest) is complete; older revisions' diffs fill in shortly. False for single-revision imports, which diff inline.

Example response
{
  "api": {
    "id": "string",
    "owner": {
      "id": "string",
      "handle": "string",
      "displayName": "string",
      "type": "user",
      "avatarUrl": "string",
      "bio": "string",
      "location": "string",
      "emailDomain": "string",
      "claimStatus": "claimed",
      "joinedAt": "2026-10-30T12:00:00Z",
      "url": "string",
      "htmlUrl": "string"
    },
    "slug": "string",
    "name": "string",
    "displayName": "string",
    "visibility": "public",
    "description": "string",
    "category": "ai-machine-learning",
    "readme": "string",
    "providerName": "string",
    "homepageUrl": "string",
    "logoUrl": "string",
    "isVerified": true,
    "license": {
      "name": "string",
      "spdxId": "string",
      "url": "string"
    },
    "contact": {
      "name": "string",
      "url": "string",
      "email": "string"
    },
    "externalDocs": {
      "url": "string",
      "description": "string"
    },
    "sources": [
      {
        "id": "string",
        "type": "direct_url",
        "url": "string",
        "extractor": "docusaurus-openapi-docs",
        "pages": [
          {
            "url": "string",
            "checkedAt": "2026-10-30T12:00:00Z",
            "changedAt": "2026-10-30T12:00:00Z",
            "contentHash": "string",
            "operationCount": 0
          }
        ],
        "requestMethod": "GET",
        "requestContentType": "string",
        "discoveredVia": "string",
        "isPrimary": true,
        "refetchEnabled": true,
        "lastCheckedAt": "2026-10-30T12:00:00Z",
        "lastStatus": "updated",
        "lastError": "string",
        "createdAt": "2026-10-30T12:00:00Z"
      }
    ],
    "versions": [
      {
        "label": "string",
        "stability": "ga",
        "isDefault": true,
        "sortRank": 0,
        "releasedAt": "2026-10-30T12:00:00Z",
        "eolAt": "2026-10-30T12:00:00Z"
      }
    ],
    "lastCheckedAt": "2026-10-30T12:00:00Z",
    "lastUpdatedAt": "2026-10-30T12:00:00Z",
    "latestVersionRef": "string",
    "versionCount": 0,
    "retiredAt": "2026-10-30T12:00:00Z",
    "starCount": 0,
    "consumerCount": 0,
    "createdAt": "2026-10-30T12:00:00Z",
    "updatedAt": "2026-10-30T12:00:00Z",
    "url": "string",
    "htmlUrl": "string",
    "viewer": {
      "canRead": true,
      "canWrite": true,
      "canAdmin": true
    }
  },
  "revision": {
    "publishedAt": "2026-10-30T12:00:00Z",
    "isLatest": true,
    "hasDocument": true,
    "documentUrl": "string",
    "commit": {
      "sha": "string",
      "message": "string",
      "date": "2026-10-30T12:00:00Z",
      "htmlUrl": "string"
    },
    "linkedRepositoryRun": {
      "repository": "string",
      "sha": "string",
      "runId": "string",
      "runAttempt": "string",
      "workflowRef": "string",
      "htmlUrl": "string"
    },
    "specType": "openapi",
    "specVersion": "string",
    "documentVersion": "string",
    "license": {
      "name": "string",
      "spdxId": "string",
      "url": "string"
    },
    "contact": {
      "name": "string",
      "url": "string",
      "email": "string"
    },
    "externalDocs": {
      "url": "string",
      "description": "string"
    },
    "retrievedAt": "2026-10-30T12:00:00Z",
    "sourceType": "direct_url",
    "derivedFrom": {
      "pages": [
        {
          "url": "string",
          "checkedAt": "2026-10-30T12:00:00Z",
          "changedAt": "2026-10-30T12:00:00Z",
          "contentHash": "string",
          "operationCount": 0
        }
      ],
      "snapshotAt": "2026-10-30T12:00:00Z",
      "extractor": "string",
      "repairs": [
        {
          "repair": "string",
          "at": "string"
        }
      ]
    },
    "operationCount": 0,
    "schemaCount": 0,
    "serverUrl": "string",
    "authSchemes": [
      "apiKey"
    ],
    "documentFormat": "json",
    "byteSize": 0,
    "contentHash": "string",
    "contentRef": "string",
    "externalRefs": {
      "fileCount": 0,
      "refCount": 0,
      "files": [
        {
          "path": "string",
          "refs": 0
        }
      ]
    },
    "url": "string",
    "htmlUrl": "string"
  },
  "deduped": true,
  "isNewApi": true,
  "docsUrl": "string",
  "diffsPending": true
}

400 application/json

Binds a concrete HTTP Status to the shared ApiError body.

object

The uniform error envelope returned for every non-2xx response.

codeenumrequiredbadRequestunauthorizedforbiddennotFoundconflictunprocessablegonepayloadTooLargeunsupportedMediaTypedocumentTooLargedocumentRefersToOtherFileswebhookLimitReachedrateLimitedinternalunavailablebadGatewaynotImplemented

Machine-readable error category. Each value pairs with one HTTP status.

messagestringrequired

Human-readable summary safe to surface to end users.

requestIdstringrequired

Correlates the response with server logs for support.

detailsarray of ErrorDetail
Example response
{
  "code": "badRequest",
  "message": "string",
  "requestId": "string",
  "details": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

401 application/json

Binds a concrete HTTP Status to the shared ApiError body.

object

The uniform error envelope returned for every non-2xx response.

codeenumrequiredbadRequestunauthorizedforbiddennotFoundconflictunprocessablegonepayloadTooLargeunsupportedMediaTypedocumentTooLargedocumentRefersToOtherFileswebhookLimitReachedrateLimitedinternalunavailablebadGatewaynotImplemented

Machine-readable error category. Each value pairs with one HTTP status.

messagestringrequired

Human-readable summary safe to surface to end users.

requestIdstringrequired

Correlates the response with server logs for support.

detailsarray of ErrorDetail
Example response
{
  "code": "badRequest",
  "message": "string",
  "requestId": "string",
  "details": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

403 application/json

Binds a concrete HTTP Status to the shared ApiError body.

object

The uniform error envelope returned for every non-2xx response.

codeenumrequiredbadRequestunauthorizedforbiddennotFoundconflictunprocessablegonepayloadTooLargeunsupportedMediaTypedocumentTooLargedocumentRefersToOtherFileswebhookLimitReachedrateLimitedinternalunavailablebadGatewaynotImplemented

Machine-readable error category. Each value pairs with one HTTP status.

messagestringrequired

Human-readable summary safe to surface to end users.

requestIdstringrequired

Correlates the response with server logs for support.

detailsarray of ErrorDetail
Example response
{
  "code": "badRequest",
  "message": "string",
  "requestId": "string",
  "details": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

422 application/json

Binds a concrete HTTP Status to the shared ApiError body.

object

The uniform error envelope returned for every non-2xx response.

codeenumrequiredbadRequestunauthorizedforbiddennotFoundconflictunprocessablegonepayloadTooLargeunsupportedMediaTypedocumentTooLargedocumentRefersToOtherFileswebhookLimitReachedrateLimitedinternalunavailablebadGatewaynotImplemented

Machine-readable error category. Each value pairs with one HTTP status.

messagestringrequired

Human-readable summary safe to surface to end users.

requestIdstringrequired

Correlates the response with server logs for support.

detailsarray of ErrorDetail
Example response
{
  "code": "badRequest",
  "message": "string",
  "requestId": "string",
  "details": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

Changes

Operation history
Nov 2, 2026ed0217ce7303
  • endpointadded