Redocly Scout (1.0)

Download OpenAPI description
openapi.json
openapi.yaml
Overview
API Support team@redocly.com
License Redocly
 Terms of Service
Languages
Servers
Mock server
https://redocly.com/_mock/docs/realm/scout/api/openapi/
Production main server.
https://{host}/api/

Upsert remote

Request

Upsert remote. If remote with the same mountPath and type already exists the remote object is returned. If the type doesn't match the existing remote, a 409 error is returned. Otherwise, a new remote is created.

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
Bodyapplication/json
mountPathstringrequired

Remote target path.

Example: "apis/test/@v1"
typestringrequired

Remote type. TODO: Add discriminator by type and add other fields for GIT and URL remote types.

Enum"CICD""GIT""URL"
Example: "CICD"
autoSyncboolean

Auto sync changes to remote.

autoMergeboolean

Auto merge changes from remote.

providerTypestring(enum)(GitProviderType)

Git provider type.

Enum"GITHUB_CLOUD""GITHUB_SERVER""GITLAB_CLOUD""GITLAB_SELF_MANAGED""BITBUCKET_CLOUD""BITBUCKET_DATACENTER""AZURE"
curl -i -X POST \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/remotes' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "mountPath": "apis/test/@v1",
    "type": "CICD",
    "autoSync": true,
    "autoMerge": true,
    "providerType": "GITHUB_CLOUD"
  }'

Responses

Remote created.

Bodyapplication/json
mountPathstringrequired

Remote target path.

Example: "apis/test/@v1"
typestringrequired

Remote type. TODO: Add discriminator by type and add other fields for GIT and URL remote types.

Enum"CICD""GIT""URL"
Example: "CICD"
autoSyncboolean

Auto sync changes to remote.

autoMergeboolean

Auto merge changes from remote.

createdAtstring(date-time)read-only
updatedAtstring(date-time)read-only
providerTypestring(enum)(GitProviderType)

Git provider type.

Enum"GITHUB_CLOUD""GITHUB_SERVER""GITLAB_CLOUD""GITLAB_SELF_MANAGED""BITBUCKET_CLOUD""BITBUCKET_DATACENTER""AZURE"
namespaceIdstringread-only
repositoryIdstringread-only
projectIdstring or nullread-only
mountBranchNamestringread-only
contentPathstringread-only
credentialIdstringread-only
branchNamestringread-only
contentTypestringread-only
Enum"FOLDER""FILE"
Example: "FILE"
idstringread-onlyrequired

Remote ID.

Example: "rem_01h2captefvs9bpg3v6twqqj9n"
Response
application/json
{
  "mountPath": "apis/test/@v1",
  "type": "CICD",
  "autoSync": true,
  "autoMerge": true,
  "createdAt": "2023-06-07T00:00:00Z",
  "updatedAt": "2023-06-07T00:00:00Z",
  "providerType": "GITHUB_CLOUD",
  "namespaceId": "string",
  "repositoryId": "string",
  "projectId": "string",
  "mountBranchName": "string",
  "contentPath": "string",
  "credentialId": "string",
  "branchName": "string",
  "contentType": "FILE",
  "id": "rem_01h2captefvs9bpg3v6twqqj9n"
}

Push files to remote

Request

Push discovered files as a remote content. Files should be sent as a multipart/form-data. Commit details like commit message and author can be sent as a JSON object in the commit field.

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
remoteIdstring(ulid)required

ID of the remote.

Example: rem_01h1s5z6vf2mm1mz3hevnn9va7
Bodymultipart/form-data
commitobjectrequired

Commit details.

commit.​namespacestring

Git repo namespace (organization login for GitHub).

Example: "Redocly"
commit.​repositorystring

Git repo name.

Example: "redoc"
commit.​messagestringrequired

Commit message.

Example: "chore: Add new API"
commit.​authorobjectrequired
commit.​author.​nameanyrequired

Commit author name.

Example: "John Doe"
commit.​author.​emailstring(email)required

Commit author email.

Example: "johndoe@example.com"
commit.​author.​imagestring

Commit author image URL. If not provided, the default image is used. If the image may not accessible, data url can be used.

jobIdstring(ulid)required

ID of the PROCESS_GIT_REPO job, if any.

Example: "job_01f1q3q1q1q1q1q1q1q1q1q1q1"
replaceboolean

Whether to replace the existing files. If provided, all files from the remote are removed and the new files are added. If not provided, the existing files are kept and the new files are added, overwriting the existing files where they overlap.

Default false
Example: true
filesobject

Map of files to upload.

curl -i -X POST \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/remotes/{remoteId}/push' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'commit[namespace]=Redocly' \
  -F 'commit[repository]=redoc' \
  -F 'commit[message]=chore: Add new API' \
  -F 'commit[author][name]=John Doe' \
  -F 'commit[author][email]=johndoe@example.com' \
  -F 'commit[author][image]=string' \
  -F jobId=job_01f1q3q1q1q1q1q1q1q1q1q1q1 \
  -F replace=true \
  -F 'files[property1]=string' \
  -F 'files[property2]=string'

Responses

Content pushed.

Bodyapplication/json
One of:
idstring(ulid)read-onlyrequired

Pull request Id.

Example: "pr_01h1s5z6vf2mm1mz3hevnn9va7"
numberintegerread-onlyrequired

Pull request number.

Example: 1
branchNamestring<= 512 charactersrequired

Branch name.

Example: "main"
titlestring<= 512 charactersrequired

PR title.

descriptionstring

PR description.

statusstringrequired

PR status.

Default "OPEN"
Enum"OPEN""CLOSED""MERGED"
isDraftboolean

Indicates whether or not the pull request is a draft.

reviewersArray of objectsread-onlyrequired

List of reviewers.

Default []
reviewers[].​idstring(ulid)read-onlyrequired

User id.

Example: "usr_01h1s5z6vf2mm1mz3hevnn9va7"
reviewers[].​firstNamestringread-onlyrequired

User first name.

reviewers[].​lastNamestringread-onlyrequired

User last name.

createdByobjectread-onlyrequired

User who create PR.

createdBy.​idstring(ulid)read-onlyrequired

User id.

Example: "usr_01h1s5z6vf2mm1mz3hevnn9va7"
createdBy.​firstNamestringread-onlyrequired

User first name.

createdBy.​lastNamestringread-onlyrequired

User last name.

closedByIdstring(ulid)read-only

User id who close PR.

Example: "usr_01h1s5z6vf2mm1mz3hevnn9va7"
mergedByIdstring(ulid)read-only

User id who merged PR.

Example: "usr_01h1s5z6vf2mm1mz3hevnn9va7"
organizationIdstringread-onlyrequired

Organization ID.

organizationobject

Organization.

projectIdstringread-onlyrequired

Project ID.

projectobject

Project.

reviewsArray of objects

list of reviews.

createdAtstring(date-time)read-onlyrequired

Created date.

updatedAtstring(date-time)read-onlyrequired

Updated date.

Response
application/json
{
  "id": "pr_01h1s5z6vf2mm1mz3hevnn9va7",
  "number": 1,
  "branchName": "main",
  "title": "string",
  "description": "string",
  "status": "OPEN",
  "isDraft": true,
  "reviewers": [],
  "createdBy": {
    "id": "usr_01h1s5z6vf2mm1mz3hevnn9va7",
    "firstName": "string",
    "lastName": "string"
  },
  "closedById": "usr_01h1s5z6vf2mm1mz3hevnn9va7",
  "mergedById": "usr_01h1s5z6vf2mm1mz3hevnn9va7",
  "organizationId": "string",
  "organization": {
    "name": "string"
  },
  "projectId": "string",
  "project": {
    "name": "string"
  },
  "reviews": [
    { … }
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Create a job todo

Request

Git provider webhook triggers Scout to create a job todo. Similarly, a lint job started or completed triggers jobs todo. Since Scout is stateless and distributed, this is the API for storing things to do. It's also a way to communicate with Scout by making jobs for it to do too (such as communicating status back to Git). Finally, it can be used to trigger Scout to update again in the case of a GitHub webhook outage.

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
Headers
x-redocly-scout-versionstring

Scout version.

Example: 1.0.0
Bodyapplication/json
typestringrequired

Type of job.

Enum"PROCESS_GIT_REPO""UPDATE_STATUS"
providerIdstring

Git provider identifier (appId for GitHub).

providerTypestringrequired

Git provider type.

Enum"GITHUB_CLOUD""GITHUB_SERVER""GITLAB_CLOUD""GITLAB_SELF_MANAGED""BITBUCKET_CLOUD""BITBUCKET_DATACENTER""AZURE"
namespaceIdstringrequired

Git repo namespace id (organization login for GitHub).

repositoryIdstringrequired

Git repo id.

branchstringrequired

Git branch name.

commitShastringrequired

Git commit SHA.

isMainBranchboolean

True if branch is main.

Default false
prIdstring

Git pull request ID.

parentJobIdstring(ulid)

ID of the parent job, if any.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
checksArray of objects(GitCommitCheck)

Commit status checks.

metadataobject(JobMetadata)

Additional information about job.

curl -i -X POST \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/scout/todos' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-redocly-scout-version: 1.0.0' \
  -d '{
    "type": "PROCESS_GIT_REPO",
    "providerId": "string",
    "providerType": "GITHUB_CLOUD",
    "namespaceId": "string",
    "repositoryId": "string",
    "branch": "string",
    "commitSha": "string",
    "isMainBranch": false,
    "prId": "string",
    "parentJobId": "sjob_01h2t9ksv7vmsvbhh5ty40zctw",
    "checks": [
      {
        "name": "Scorecard - Compliance API",
        "status": "IN_PROGRESS",
        "description": "string",
        "targetUrl": "string"
      }
    ],
    "metadata": {
      "errorMessage": "string",
      "errorStack": "string"
    }
  }'

Responses

Created.

Bodyapplication/json
idstring(ulid)read-onlyrequired

ID of the job.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
statusstringread-onlyrequired

Job status.

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
typestringrequired

Type of job.

Enum"PROCESS_GIT_REPO""UPDATE_STATUS"
organizationIdstringread-onlyrequired

Organization ID.

projectIdstringread-onlyrequired

Project ID.

providerIdstring

Git provider identifier (appId for GitHub).

providerTypestringrequired

Git provider type.

Enum"GITHUB_CLOUD""GITHUB_SERVER""GITLAB_CLOUD""GITLAB_SELF_MANAGED""BITBUCKET_CLOUD""BITBUCKET_DATACENTER""AZURE"
namespaceIdstringrequired

Git repo namespace id (organization login for GitHub).

repositoryIdstringrequired

Git repo id.

branchstringrequired

Git branch name.

commitShastringrequired

Git commit SHA.

isMainBranchboolean

True if branch is main.

Default false
prIdstring

Git pull request ID.

attemptsintegerread-onlyrequired

Number of attempts to process the job.

parentJobIdstring(ulid)

ID of the parent job, if any.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
checksArray of objects(GitCommitCheck)

Commit status checks.

metadataobject(JobMetadata)

Additional information about job.

startedAtstring(date-time)read-only

Job start date.

createdAtstring(date-time)read-onlyrequired

Job creation date.

updatedAtstring(date-time)read-onlyrequired

Job last update date.

Response
application/json
{
  "id": "sjob_01h2t9ksv7vmsvbhh5ty40zctw",
  "status": "PENDING",
  "type": "PROCESS_GIT_REPO",
  "organizationId": "string",
  "projectId": "string",
  "providerId": "string",
  "providerType": "GITHUB_CLOUD",
  "namespaceId": "string",
  "repositoryId": "string",
  "branch": "string",
  "commitSha": "string",
  "isMainBranch": false,
  "prId": "string",
  "attempts": 0,
  "parentJobId": "sjob_01h2t9ksv7vmsvbhh5ty40zctw",
  "checks": [
    { … }
  ],
  "metadata": {
    "scoutVersion": "1.0.0",
    "errorMessage": "string",
    "errorStack": "string"
  },
  "startedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

List all todos

Request

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
Query
afterstring

Use the endCursor as a value for the after parameter to get the next page.

Example: after=a25fgaksjf23la==
beforestring

Use the startCursor as a value for the before parameter to get the next page.

Example: before=bfg23aksjf23zb1==
sortstring

This list is currently not sortable by other properties. It is sorted by the id descending (-id) by default. To reverse the sort order, use id as the value.

Default "-id"
filterstring
Example: filter=status:approved,pending updatedAt:2020-01-01..2022-01-01
limitinteger[ 1 .. 100 ]

Use to return a number of results per page. If there is more data, use in combination with after to page through the data.

Default 10
Headers
x-redocly-scout-versionstring

Scout version.

Example: 1.0.0
curl -i -X GET \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/scout/todos?after=a25fgaksjf23la%3D%3D&before=bfg23aksjf23zb1%3D%3D&filter=status%3Aapproved%2Cpending%20updatedAt%3A2020-01-01..2022-01-01&limit=10&sort=-id' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-redocly-scout-version: 1.0.0'

Responses

OK.

Bodyapplication/json
objectstringrequired
Value "list"
pageobject(Page)required
page.​endCursorstring or nullrequired

Use with the after query parameter to load the next page of data. When null, there is no data. The cursor is opaque and internal structure is subject to change.

page.​startCursorstring or nullrequired

Use with the before query parameter to load the previous page of data. When null, there is no data. The cursor is opaque and internal structure is subject to change.

page.​hasNextPagebooleanrequired

Indicates if there is a next page with items.

page.​hasPrevPagebooleanrequired

Indicates if there is a previous page with items.

page.​limitinteger[ 1 .. 100 ]required

Value showing how many items are in the page limit.

Default 10
page.​totalinteger>= 0required

Count of items across all pages.

itemsArray of objects(Job)>= 0 itemsrequired
items[].​idstring(ulid)read-onlyrequired

ID of the job.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
items[].​statusstringread-onlyrequired

Job status.

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
items[].​typestringrequired

Type of job.

Enum"PROCESS_GIT_REPO""UPDATE_STATUS"
items[].​organizationIdstringread-onlyrequired

Organization ID.

items[].​projectIdstringread-onlyrequired

Project ID.

items[].​providerIdstring

Git provider identifier (appId for GitHub).

items[].​providerTypestringrequired

Git provider type.

Enum"GITHUB_CLOUD""GITHUB_SERVER""GITLAB_CLOUD""GITLAB_SELF_MANAGED""BITBUCKET_CLOUD""BITBUCKET_DATACENTER""AZURE"
items[].​namespaceIdstringrequired

Git repo namespace id (organization login for GitHub).

items[].​repositoryIdstringrequired

Git repo id.

items[].​branchstringrequired

Git branch name.

items[].​commitShastringrequired

Git commit SHA.

items[].​isMainBranchboolean

True if branch is main.

Default false
items[].​prIdstring

Git pull request ID.

items[].​attemptsintegerread-onlyrequired

Number of attempts to process the job.

items[].​parentJobIdstring(ulid)

ID of the parent job, if any.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
items[].​checksArray of objects(GitCommitCheck)

Commit status checks.

items[].​metadataobject(JobMetadata)

Additional information about job.

items[].​startedAtstring(date-time)read-only

Job start date.

items[].​createdAtstring(date-time)read-onlyrequired

Job creation date.

items[].​updatedAtstring(date-time)read-onlyrequired

Job last update date.

Response
application/json
{
  "object": "list",
  "page": {
    "endCursor": "string",
    "startCursor": "string",
    "hasNextPage": true,
    "hasPrevPage": true,
    "limit": 10,
    "total": 0
  },
  "items": [
    { … }
  ]
}

Process next job

Request

Retrieve and start the next available job.

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
Headers
x-redocly-scout-versionstring

Scout version.

Example: 1.0.0
curl -i -X POST \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/scout/tasks' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-redocly-scout-version: 1.0.0'

Responses

OK.

Bodyapplication/json
idstring(ulid)read-onlyrequired

ID of the job.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
statusstringread-onlyrequired

Job status.

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
typestringrequired

Type of job.

Enum"PROCESS_GIT_REPO""UPDATE_STATUS"
organizationIdstringread-onlyrequired

Organization ID.

projectIdstringread-onlyrequired

Project ID.

providerIdstring

Git provider identifier (appId for GitHub).

providerTypestringrequired

Git provider type.

Enum"GITHUB_CLOUD""GITHUB_SERVER""GITLAB_CLOUD""GITLAB_SELF_MANAGED""BITBUCKET_CLOUD""BITBUCKET_DATACENTER""AZURE"
namespaceIdstringrequired

Git repo namespace id (organization login for GitHub).

repositoryIdstringrequired

Git repo id.

branchstringrequired

Git branch name.

commitShastringrequired

Git commit SHA.

isMainBranchboolean

True if branch is main.

Default false
prIdstring

Git pull request ID.

attemptsintegerread-onlyrequired

Number of attempts to process the job.

parentJobIdstring(ulid)

ID of the parent job, if any.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
checksArray of objects(GitCommitCheck)

Commit status checks.

metadataobject(JobMetadata)

Additional information about job.

startedAtstring(date-time)read-only

Job start date.

createdAtstring(date-time)read-onlyrequired

Job creation date.

updatedAtstring(date-time)read-onlyrequired

Job last update date.

Response
application/json
{
  "id": "sjob_01h2t9ksv7vmsvbhh5ty40zctw",
  "status": "PENDING",
  "type": "PROCESS_GIT_REPO",
  "organizationId": "string",
  "projectId": "string",
  "providerId": "string",
  "providerType": "GITHUB_CLOUD",
  "namespaceId": "string",
  "repositoryId": "string",
  "branch": "string",
  "commitSha": "string",
  "isMainBranch": false,
  "prId": "string",
  "attempts": 0,
  "parentJobId": "sjob_01h2t9ksv7vmsvbhh5ty40zctw",
  "checks": [
    { … }
  ],
  "metadata": {
    "scoutVersion": "1.0.0",
    "errorMessage": "string",
    "errorStack": "string"
  },
  "startedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

List all tasks

Request

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
Query
afterstring

Use the endCursor as a value for the after parameter to get the next page.

Example: after=a25fgaksjf23la==
beforestring

Use the startCursor as a value for the before parameter to get the next page.

Example: before=bfg23aksjf23zb1==
sortstring

This list is currently not sortable by other properties. It is sorted by the id descending (-id) by default. To reverse the sort order, use id as the value.

Default "-id"
filterstring
Example: filter=status:approved,pending updatedAt:2020-01-01..2022-01-01
limitinteger[ 1 .. 100 ]

Use to return a number of results per page. If there is more data, use in combination with after to page through the data.

Default 10
Headers
x-redocly-scout-versionstring

Scout version.

Example: 1.0.0
curl -i -X GET \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/scout/tasks?after=a25fgaksjf23la%3D%3D&before=bfg23aksjf23zb1%3D%3D&filter=status%3Aapproved%2Cpending%20updatedAt%3A2020-01-01..2022-01-01&limit=10&sort=-id' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-redocly-scout-version: 1.0.0'

Responses

OK.

Bodyapplication/json
objectstringrequired
Value "list"
pageobject(Page)required
page.​endCursorstring or nullrequired

Use with the after query parameter to load the next page of data. When null, there is no data. The cursor is opaque and internal structure is subject to change.

page.​startCursorstring or nullrequired

Use with the before query parameter to load the previous page of data. When null, there is no data. The cursor is opaque and internal structure is subject to change.

page.​hasNextPagebooleanrequired

Indicates if there is a next page with items.

page.​hasPrevPagebooleanrequired

Indicates if there is a previous page with items.

page.​limitinteger[ 1 .. 100 ]required

Value showing how many items are in the page limit.

Default 10
page.​totalinteger>= 0required

Count of items across all pages.

itemsArray of objects(Job)>= 0 itemsrequired
items[].​idstring(ulid)read-onlyrequired

ID of the job.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
items[].​statusstringread-onlyrequired

Job status.

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
items[].​typestringrequired

Type of job.

Enum"PROCESS_GIT_REPO""UPDATE_STATUS"
items[].​organizationIdstringread-onlyrequired

Organization ID.

items[].​projectIdstringread-onlyrequired

Project ID.

items[].​providerIdstring

Git provider identifier (appId for GitHub).

items[].​providerTypestringrequired

Git provider type.

Enum"GITHUB_CLOUD""GITHUB_SERVER""GITLAB_CLOUD""GITLAB_SELF_MANAGED""BITBUCKET_CLOUD""BITBUCKET_DATACENTER""AZURE"
items[].​namespaceIdstringrequired

Git repo namespace id (organization login for GitHub).

items[].​repositoryIdstringrequired

Git repo id.

items[].​branchstringrequired

Git branch name.

items[].​commitShastringrequired

Git commit SHA.

items[].​isMainBranchboolean

True if branch is main.

Default false
items[].​prIdstring

Git pull request ID.

items[].​attemptsintegerread-onlyrequired

Number of attempts to process the job.

items[].​parentJobIdstring(ulid)

ID of the parent job, if any.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
items[].​checksArray of objects(GitCommitCheck)

Commit status checks.

items[].​metadataobject(JobMetadata)

Additional information about job.

items[].​startedAtstring(date-time)read-only

Job start date.

items[].​createdAtstring(date-time)read-onlyrequired

Job creation date.

items[].​updatedAtstring(date-time)read-onlyrequired

Job last update date.

Response
application/json
{
  "object": "list",
  "page": {
    "endCursor": "string",
    "startCursor": "string",
    "hasNextPage": true,
    "hasPrevPage": true,
    "limit": 10,
    "total": 0
  },
  "items": [
    { … }
  ]
}

Get task

Request

Get task.

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
jobIdstring(ulid)required

Job ID.

Example: sjob_01h2t9ksv7vmsvbhh5ty40zctw
Headers
x-redocly-scout-versionstring

Scout version.

Example: 1.0.0
curl -i -X GET \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/scout/tasks/{jobId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-redocly-scout-version: 1.0.0'

Responses

OK.

Bodyapplication/json
idstring(ulid)read-onlyrequired

ID of the job.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
statusstringread-onlyrequired

Job status.

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
typestringrequired

Type of job.

Enum"PROCESS_GIT_REPO""UPDATE_STATUS"
organizationIdstringread-onlyrequired

Organization ID.

projectIdstringread-onlyrequired

Project ID.

providerIdstring

Git provider identifier (appId for GitHub).

providerTypestringrequired

Git provider type.

Enum"GITHUB_CLOUD""GITHUB_SERVER""GITLAB_CLOUD""GITLAB_SELF_MANAGED""BITBUCKET_CLOUD""BITBUCKET_DATACENTER""AZURE"
namespaceIdstringrequired

Git repo namespace id (organization login for GitHub).

repositoryIdstringrequired

Git repo id.

branchstringrequired

Git branch name.

commitShastringrequired

Git commit SHA.

isMainBranchboolean

True if branch is main.

Default false
prIdstring

Git pull request ID.

attemptsintegerread-onlyrequired

Number of attempts to process the job.

parentJobIdstring(ulid)

ID of the parent job, if any.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
checksArray of objects(GitCommitCheck)

Commit status checks.

metadataobject(JobMetadata)

Additional information about job.

startedAtstring(date-time)read-only

Job start date.

createdAtstring(date-time)read-onlyrequired

Job creation date.

updatedAtstring(date-time)read-onlyrequired

Job last update date.

Response
application/json
{
  "id": "sjob_01h2t9ksv7vmsvbhh5ty40zctw",
  "status": "PENDING",
  "type": "PROCESS_GIT_REPO",
  "organizationId": "string",
  "projectId": "string",
  "providerId": "string",
  "providerType": "GITHUB_CLOUD",
  "namespaceId": "string",
  "repositoryId": "string",
  "branch": "string",
  "commitSha": "string",
  "isMainBranch": false,
  "prId": "string",
  "attempts": 0,
  "parentJobId": "sjob_01h2t9ksv7vmsvbhh5ty40zctw",
  "checks": [
    { … }
  ],
  "metadata": {
    "scoutVersion": "1.0.0",
    "errorMessage": "string",
    "errorStack": "string"
  },
  "startedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Update job

Request

Scout sends this API request after completing a job. Supports only PROCESSING -> COMPLETED and PROCESSING -> FAILED transitions.

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
jobIdstring(ulid)required

Job ID.

Example: sjob_01h2t9ksv7vmsvbhh5ty40zctw
Headers
x-redocly-scout-versionstring

Scout version.

Example: 1.0.0
Bodyapplication/json
statusstringrequired

Job status.

Enum"COMPLETED""FAILED"
metadataobject(JobMetadata)

Additional information about job.

curl -i -X PATCH \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/scout/tasks/{jobId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-redocly-scout-version: 1.0.0' \
  -d '{
    "status": "COMPLETED",
    "metadata": {
      "errorMessage": "string",
      "errorStack": "string"
    }
  }'

Responses

OK.

Bodyapplication/json
idstring(ulid)read-onlyrequired

ID of the job.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
statusstringread-onlyrequired

Job status.

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
typestringrequired

Type of job.

Enum"PROCESS_GIT_REPO""UPDATE_STATUS"
organizationIdstringread-onlyrequired

Organization ID.

projectIdstringread-onlyrequired

Project ID.

providerIdstring

Git provider identifier (appId for GitHub).

providerTypestringrequired

Git provider type.

Enum"GITHUB_CLOUD""GITHUB_SERVER""GITLAB_CLOUD""GITLAB_SELF_MANAGED""BITBUCKET_CLOUD""BITBUCKET_DATACENTER""AZURE"
namespaceIdstringrequired

Git repo namespace id (organization login for GitHub).

repositoryIdstringrequired

Git repo id.

branchstringrequired

Git branch name.

commitShastringrequired

Git commit SHA.

isMainBranchboolean

True if branch is main.

Default false
prIdstring

Git pull request ID.

attemptsintegerread-onlyrequired

Number of attempts to process the job.

parentJobIdstring(ulid)

ID of the parent job, if any.

Example: "sjob_01h2t9ksv7vmsvbhh5ty40zctw"
checksArray of objects(GitCommitCheck)

Commit status checks.

metadataobject(JobMetadata)

Additional information about job.

startedAtstring(date-time)read-only

Job start date.

createdAtstring(date-time)read-onlyrequired

Job creation date.

updatedAtstring(date-time)read-onlyrequired

Job last update date.

Response
application/json
{
  "id": "sjob_01h2t9ksv7vmsvbhh5ty40zctw",
  "status": "PENDING",
  "type": "PROCESS_GIT_REPO",
  "organizationId": "string",
  "projectId": "string",
  "providerId": "string",
  "providerType": "GITHUB_CLOUD",
  "namespaceId": "string",
  "repositoryId": "string",
  "branch": "string",
  "commitSha": "string",
  "isMainBranch": false,
  "prId": "string",
  "attempts": 0,
  "parentJobId": "sjob_01h2t9ksv7vmsvbhh5ty40zctw",
  "checks": [
    { … }
  ],
  "metadata": {
    "scoutVersion": "1.0.0",
    "errorMessage": "string",
    "errorStack": "string"
  },
  "startedAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Push status

Request

Scout uses this to periodically report it's status back to main api.

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
Headers
x-redocly-scout-versionstring

Scout version.

Example: 1.0.0
Bodyapplication/json
hostnamestringrequired

Hostname of Scout instance.

pidintegerrequired

Process ID.

versionstringrequired

Scout version.

diskobjectrequired

Disk usage.

disk.​sizeintegerrequired

Total disk size.

disk.​usedintegerrequired

Used disk size.

disk.​availableintegerrequired

Available disk size.

disk.​unitstringrequired

Disk size unit.

Enum"B""KB""MB""GB""TB"
Example: "MB"
jobsobjectrequired

Scout jobs.

jobs.​activeintegerrequired

Number of active jobs.

jobs.​maxintegerrequired

Maximum number of jobs.

curl -i -X POST \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/scout/status' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-redocly-scout-version: 1.0.0' \
  -d '{
    "hostname": "string",
    "pid": 0,
    "version": "string",
    "disk": {
      "size": 0,
      "used": 0,
      "available": 0,
      "unit": "MB"
    },
    "jobs": {
      "active": 0,
      "max": 0
    }
  }'

Responses

No content.

Response
application/problem+json
{
  "type": "/some/uri-reference",
  "title": "some title for the error situation",
  "status": 400,
  "detail": "some description for the error situation",
  "instance": "/some/uri-reference#specific-occurrence-context",
  "object": "problem"
}

Get metadata validation result

Request

Validate api metadata against "metadataSchema" in project's config file.

Path
orgIdstringrequired

Organization ID.

Example: acme-inc
projectIdstringrequired

Project ID.

Example: my-project
Headers
x-redocly-scout-versionstring

Scout version.

Example: 1.0.0
Bodyapplication/json
object(Metadata)

Any object shape.

curl -i -X POST \
  'https://redocly.com/_mock/docs/realm/scout/api/openapi/orgs/{orgId}/projects/{projectId}/scout/metadata/validate' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-redocly-scout-version: 1.0.0' \
  -d '{
    "department": "IT"
  }'

Responses

OK.

Bodyapplication/json
isValidbooleanrequired
Example: false
errorsArray of objects

Array of metadata validation errors.

Example: [{"instancePath":"","schemaPath":"#/required","keyword":"required","params":{"missingProperty":"owner"},"message":"must have required property 'owner'"}]
Response
application/json
{
  "isValid": false,
  "errors": [
    { … }
  ]
}