Documentation Archive

Developer

Xcode Server API Reference

On This Page

Bots

Bots are processes that Xcode Server runs to perform integrations on the current version of a project in a source code repository. An integration is a single run of a bot. Integrations consist of building, analyzing, testing, and archiving the apps (or other software products) defined in your Xcode projects. With Xcode Server able to access the source code repositories of those projects, you can configure bots to perform continuous integrations on them. Bots can be configured to run in the following ways:

  • Every time a change is committed to the repository

  • On a regular schedule, such as hourly, daily, or weekly

  • When manually initiated

Creating a New Bot

POST

/bots

Creates a new bot.

Example

https://server.mycompany.com:20343/api/bots

Request

Body

  1. {
  2. "configuration": {
  3. ...
  4. },
  5. "name": "Sketch"
  6. }

Response: 201

Headers

  1. Content-Type: application/json
  2. Location: https://server.mycompany.com:20343/api/bots/6f0faeb1cc4c55e174cac5ff8100f13b
  3. X-XCSAPIVersion: 4

Body

  1. {
  2. "_id": "6f0faeb1cc4c55e174cac5ff8100f13b",
  3. "_rev": "11-1339f79e58100e9befc1451fe906e142",
  4. "configuration": {
  5. ...
  6. },
  7. "name": "Sketch",
  8. "doc_type": "bot"
  9. }

Response: 400

Body

  1. {
  2. status: 400,
  3. message: "The body is empty"
  4. }

Retrieving Bots

GET

/bots

Retrieves a list of bots.

Example

https://server.mycompany.com:20343/api/bots

Response: 200

Body

  1. {
  2. "counter": 1,
  3. "results": [
  4. {
  5. "_id": "6f0faeb1cc4c55e174cac5ff8100f13b",
  6. "_rev": "11-1339f79e58100e9befc1451fe906e142",
  7. "configuration": {
  8. ...
  9. },
  10. "name": "Sketch",
  11. "doc_type": "bot"
  12. }
  13. ]
  14. }

Retrieving a Bot

POST

/bots/{id}

Retrieves a single bot.

Example

https://server.mycompany.com:20343/api/bots/6f0faeb1cc4c55e174cac5ff8100f13b

Parameters

id (required)

  • The bot ID.

  • Type: string

  • Example: 6f0faeb1cc4c55e174cac5ff8100f13b

Response: 200

Body

  1. {
  2. "_id": "6f0faeb1cc4c55e174cac5ff8100f13b",
  3. "_rev": "11-1339f79e58100e9befc1451fe906e142",
  4. "configuration": {
  5. ...
  6. },
  7. "name": "Sketch",
  8. "doc_type": "bot"
  9. }

Response: 404

Body

  1. {
  2. "status": 404,
  3. "message": "Bot not found"
  4. }

Updating a Bot

PATCH

/bots/{id}

Updates a single bot. This method will merge the provided blueprint with the existing authenticated source control blueprint.

Example

https://server.mycompany.com:20343/api/bots/6f0faeb1cc4c55e174cac5ff8100f13b

Parameters

id (required)

  • The bot ID.

  • Type: string

  • Example: 6f0faeb1cc4c55e174cac5ff8100f13b

Request

Body

  1. {
  2. "name": "Sketch Demo"
  3. }

Response: 200

Body

  1. {
  2. "_id": "6f0faeb1cc4c55e174cac5ff8100f13b",
  3. "_rev": "11-1339f79e58100e9befc1451fe906e142",
  4. "configuration": {
  5. ...
  6. },
  7. "name": "Sketch",
  8. "doc_type": "bot"
  9. }

Response: 404

Body

  1. {
  2. "status": 404,
  3. "message": "Bot not found"
  4. }

Deleting a Bot

DELETE

/bots/{id}

Deletes a single bot.

Example

https://server.mycompany.com:20343/api/bots/6f0faeb1cc4c55e174cac5ff8100f13b

Parameters

id (required)

  • The bot ID.

  • Type: string

  • Example: 6f0faeb1cc4c55e174cac5ff8100f13b

Request

Body

  1. {
  2. "name": "Sketch Demo"
  3. }

Response: 204

Response: 204

Body

  1. {
  2. "status": 404,
  3. "message": "Bot not found"
  4. }

Duplicating a Bot

POST

/bots/{id}/duplicate

Duplicates an existing bot. Optionally, the body of the request may specify the properties to be set after the bot has been duplicated. If the body is empty, the duplicated bot will be an exact copy of the original.

Example

https://server.mycompany.com:20343/api/bots/6f0faeb1cc4c55e174cac5ff8100f13b/duplicate

Parameters

id (required)

  • The bot ID.

  • Type: string

  • Example: 6f0faeb1cc4c55e174cac5ff8100f13b

Request

Body

  1. {
  2. "name": "My new bot"
  3. }

Response: 201

Headers

  1. Content-Type: application/json
  2. Location: https://server.mycompany.com:20343/api/bots/e2d2444f20d5a86015fdc69adb000c67
  3. X-XCSAPIVersion: 4

Body

  1. {
  2. "_id": "add0cd57-42a4-4684-9a11-7fb01cb86d5a",
  3. "_rev": "11-497507e3-9078-4664-be8b-022ec0f13ee7",
  4. "configuration": {
  5. ...
  6. },
  7. "name": "My new bot",
  8. "doc_type": "bot"
  9. }

Response: 404

Body

  1. {
  2. "status": 404,
  3. "message": "Bot not found"
  4. }