Introduction

Request and Response Format

All input parameters are expected to be sent in the body as JSON-encoded data. Likewise, all responses are sent as JSON-encoded data as specified in the respective sections.

Endpoint

The end point for all API calls is https://scrutinizer-ci.com/api. The paths below must be appended to this endpoint.

Authentication

Some requests require authentication. For those requests you must authenticate by appending ?access_token=your-access-token to the given endpoint. Users can obtain access tokens for their accounts via their profile; there currently exists no dedicated endpoint for creating tokens programmatically.

Meta

Returns IP addresses that we use for pulling your code, or for sending hooks. You can use it if you would like to whitelist certain IPs in your firewall.

Endpoint: GET meta

Sample Response:

{
    "pull_ips": [
        "12.34.56.78",
        "34.56.7.8"
    ],
    "hook_ips": [
        "12.34.56.78",
        "34.56.7.8"
    ]
}

Organization Repositories

Listing Organization Repositories

This endpoint shows all repositories that are associated with an organization.

Endpoints

GET organizations/{slug}/repositories

Parameters

page:The page which you want to view (1-based). Defaults to 1.
per_page:The number of repositories which should be listed per page (minimum: 1 - maximum: 100). Defaults to 20.

Sample Response

{
    "page": 1,
    "limit": 20,
    "_links": {
        "self": {
            "href": "\/app_test.php\/api\/organizations\/scrutinizer\/repositories?page=1&per_page=20"
        },
        "first": {
            "href": "\/app_test.php\/api\/organizations\/scrutinizer\/repositories?page=1&per_page=20"
        },
        "next": {
            "href": "\/app_test.php\/api\/organizations\/scrutinizer\/repositories?page=2&per_page=20"
        }
    },
    "_embedded": {
        "repositories": [

        ]
    }
}

Associate Repository with Organization

This endpoint associates an already existing repository with the organization. If the repository has not be added on Scrutinizer, please use the Add Repository endpoint instead.

Endpoint

PUT organizations/{slug}/repositories

Request Attributes

repository:The qualified name of the repository including its type, for example g/scrutinizer-ci/web, b/scrutinizer-ci/web, etc.

Status Codes

200:On success
400:If there is a validation error

Sample Request Body

{
    "repository": "g/scrutinizer-ci/web"
}

Disassociate Repository from Organization

This endpoint disassociates a repository from an organization. It does not actually remove the repository from Scrutinizer.

Endpoint

GitHub:DELETE organizations/{slug}/repositories/g/{login}/{name}
Bitbucket:DELETE organizations/{slug}/repositories/b/{username}/{repoSlug}
GitLab:DELETE organizations/{slug}/repositories/gl/{instanceSlug}/{namespace}/{name}
Plain Git:DELETE organizations/{slug}/repositories/gp/{name}

Status Codes

200:On success
400:If there is a validation error

Organization Members

Viewing Organization Members

Endpoint

GET organizations/{slug}/members

Sample Response

{
    "page": 1,
    "limit": 20,
    "_links": {
        "self": {
            "href": "\/api\/organizations\/scrutinizer\/members?page=1&per_page=20"
        },
        "first": {
            "href": "\/api\/organizations\/scrutinizer\/members?page=1&per_page=20"
        },
        "next": {
            "href": "\/api\/organizations\/scrutinizer\/members?page=2&per_page=20"
        }
    },
    "_embedded": {
        "memberships": [
            {
                "created_at": "2015-01-27T09:27:16+0000",
                "user": {
                    "display_name": "Johannes Schmitt",
                    "uuid": "e00c833a-624c-4982-9901-b195ee3d339f",
                    "email": "[email protected]"
                },
                "role": "admin"
            }
        ]
    }
}

Adding/Updating Organization Member

This endpoint is used to add, or update organization members.

Endpoint

PUT organizations/{slug}/members

Request Attributes

email:The user?s email that should be added to the organization.
role:The user?s access permissions; available permissions: admin, master (can manage repositories/members/teams), billing, member; default: member

Status Codes

200:On success

Sample Request Body

{
    "email": "[email protected]",
    "role": "admin"
}

Sample Response

{
    "created_at": "2015-01-27T09:27:39+0000",
    "user": {
        "display_name": "Foo Bar",
        "uuid": "2a79bd68-abbf-494f-8132-d365183061d9",
        "email": "[email protected]"
    },
    "role": "admin"
}

Removing Organization Member

This removes a user from an organization. It also automatically removes this user from all teams of that organization, and revokes all permissions that this user had.

Endpoint

DELETE organizations/{slug}/members/{userUuid}

Status Codes

200:On success

Organization Configs

Viewing Organization Configurations

Endpoint

GET organizations/{slug}/configs

Sample Response

{
    "page": 1,
    "limit": 20,
    "_links": {
        "self": {
            "href": "\/api\/organizations\/scrutinizer\/configs?page=1&per_page=20"
        },
        "first": {
            "href": "\/api\/organizations\/scrutinizer\/configs?page=1&per_page=20"
        },
        "next": {
            "href": "\/api\/organizations\/scrutinizer\/configs?page=2&per_page=20"
        }
    },
    "_embedded": {
        "configs": [
            {
                "created_at": "2015-01-26T11:55:07+0000",
                "modified_at": "2015-01-26T11:55:07+0000",
                "name": "Test Config",
                "uuid": "40e5c0fd-2176-459c-85c0-acd5f2d5886e",
                "_links": {
                    "self": {
                        "href": "\/api\/organizations\/scrutinizer\/configs\/40e5c0fd-2176-459c-85c0-acd5f2d5886e"
                    }
                }
            },
            {
                "created_at": "2015-01-26T11:55:30+0000",
                "modified_at": "2015-01-26T11:55:30+0000",
                "name": "Foo",
                "uuid": "011a9862-90c6-47fb-8ae8-6f17e302a13c",
                "_links": {
                    "self": {
                        "href": "\/api\/organizations\/scrutinizer\/configs\/011a9862-90c6-47fb-8ae8-6f17e302a13c"
                    }
                }
            }
        ]
    }
}

Organization Teams

Viewing Teams

Endpoint

GET organizations/{slug}/teams

Sample Response

{
    "page": 1,
    "limit": 20,
    "_links": {
        "self": {
            "href": "\/api\/organizations\/scrutinizer\/teams?page=1&per_page=20"
        },
        "first": {
            "href": "\/api\/organizations\/scrutinizer\/teams?page=1&per_page=20"
        },
        "next": {
            "href": "\/api\/organizations\/scrutinizer\/teams?page=2&per_page=20"
        }
    },
    "_embedded": {
        "teams": [
            {
                "name": "My First Team",
                "created_at": "2015-01-27T10:12:50+0000",
                "uuid": "my-first-team-uuid",
                "_links": {
                    "self": {
                        "href": "\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid"
                    },
                    "members": {
                        "href": "\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/members"
                    },
                    "permissions": {
                        "href": "\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/permissions"
                    }
                }
            }
        ]
    }
}

Creating Team

Endpoint

POST organizations/{slug}/teams

Request Attributes

name:The team?s name

Status Codes

201:On success when the team was created.

Sample Request Body

{
    "name": "My First Team"
}

Sample Response

{
    "member_count": 0,
    "name": "My First Team",
    "created_at": "2015-01-27T10:22:10+0000",
    "uuid": "my-first-team-uuid",
    "_links": {
        "self": {
            "href": "\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid"
        },
        "members": {
            "href": "\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/members"
        },
        "permissions": {
            "href": "\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/permissions"
        }
    }
}

Deleting Team

Removes a team, and all permissions that this team had.

Endpoint

DELETE organizations/{slug}/teams/{teamUuid}

Viewing Team Permissions

Endpoint

GET organizations/{slug}/teams/{teamUuid}/permissions

Sample Response

{
    "page": 1,
    "limit": 20,
    "_links": {
        "self": {
            "href": "\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/permissions?page=1&per_page=20"
        },
        "first": {
            "href": "\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/permissions?page=1&per_page=20"
        },
        "next": {
            "href": "\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/permissions?page=2&per_page=20"
        }
    },
    "_embedded": {
        "permissions": [
            {
                "access": "developer",
                "_links": {
                    "repository": {
                        "href": "\/api\/repositories\/b\/scrutinizer-ci\/bitbucket-private"
                    }
                },
                "_embedded": {
                    "repository": {
                        "type": "b",
                        "created_at": "2015-01-27T10:22:15+0000",
                        "username": "scrutinizer-ci",
                        "repo_slug": "bitbucket-private",
                        "_links": {
                            "self": {
                                "href": "\/api\/repositories\/b\/scrutinizer-ci\/bitbucket-private"
                            }
                        },
                        "_embedded": {
                            "organization": {
                                "slug": "scrutinizer",
                                "name": "Scrutinizer Org"
                            }
                        }
                    }
                }
            }
        ]
    }
}

Adding/Updating Team Permission

This endpoint can be used to add, or update a team?s permission to one of the organization?s repositories.

Endpoints

GitHub:PUT organizations/{slug}/teams/{teamUuid}/permissions/g/{login}/{name}
Bitbucket:PUT organizations/{slug}/teams/{teamUuid}/permissions/b/{username}/{repoSlug}
GitLab:PUT organizations/{slug}/teams/{teamUuid}/permissions/gl/{instanceSlug}/{namespace}/{name}
Plain Git:PUT organizations/{slug}/teams/{teamUuid}/permissions/gp/{name}

Request Attributes

access:The access level to grant for this repository; available: admin, developer, view

Status Codes

200:On success

Sample Request Body

{
    "access": "admin"
}

Removing Team Permission

Endpoint

GitHub:DELETE organizations/{slug}/teams/{teamUuid}/permissions/g/{login}/{name}
Bitbucket:DELETE organizations/{slug}/teams/{teamUuid}/permissions/b/{username}/{repoSlug}
GitLab:DELETE organizations/{slug}/teams/{teamUuid}/permissions/gl/{instanceSlug}/{namespace}/{name}
Plain Git:DELETE organizations/{slug}/teams/{teamUuid}/permissions/gp/{name}

Status Codes

200:On success

Viewing Team Members

Endpoint

GET organizations/{slug}/teams/{teamUuid}/members

Sample Response

{
    "page": 1,
    "limit": 20,
    "_links": {
        "self": {
            "href": "\/app_test.php\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/members?page=1&per_page=20"
        },
        "first": {
            "href": "\/app_test.php\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/members?page=1&per_page=20"
        },
        "next": {
            "href": "\/app_test.php\/api\/organizations\/scrutinizer\/teams\/my-first-team-uuid\/members?page=2&per_page=20"
        }
    },
    "_embedded": {
        "members": [
            {
                "display_name": "Foo Bar",
                "email": "[email protected]",
                "uuid": "2a79bd68-abbf-494f-8132-d365183061d9"
            }
        ]
    }
}

Adding Team Member

Endpoint

PUT organizations/{slug}/teams/{teamUuid}/members

Request Attributes

email:The user?s email that should be added to the team.

Status Codes

200:On success

Sample Request Body

{
    "email": "[email protected]"
}

Removing Team Member

Endpoint

DELETE organizations/{slug}/teams/{teamUuid}/members/{userUuid}

Status Codes

200:On success

Organization Reports

Latest Reports

Retrieves the latest reports for each repository in your organization

Endpoints

GET organizations/{slug}/reports

Parameters

page:    The page which you want to view (1-based). Defaults to 1.
per_page:The number of inspections which should be listed per page (minimum: 1 - maximum: 100). Defaults to 20.

Sample Response

{
    "page": 1,
    "limit": 1,
    "_links": {
        "self": {
            "href": "\/api\/organization\/scrutinizer\/reports?page=1&per_page=1"
        },
        "first": {
            "href": "\/api\/organization\/scrutinizer\/reports?page=1&per_page=1"
        },
        "next": {
            "href": "\/api\/organization\/scrutinizer\/reports?page=2&per_page=1"
        }
    },
    "_embedded": {
        "reports": [
            {
                "date": "2014-06-24",
                "created_at": "2014-06-24T00:00:00+0000",
                "start_date": "2014-06-16T00:00:00+0000",
                "end_date": "2014-06-23T00:00:00+0000",
                "base_source_reference": "abcdef",
                "head_source_reference": "abcdef123",
                "quality_score": 5.8,
                "quality_score_change": 0.2,
                "quality_distribution": {
                    "weights": {
                        "very_good": 1,
                        "good": 1,
                        "satisfactory": 1,
                        "pass": 1,
                        "critical": 1
                    }
                },
                "nb_alerts": 29,
                "nb_alerts_change": 1,
                "nb_issues": 87,
                "nb_issues_change": 3,
                "test_coverage": 0.58,
                "test_coverage_change": 0.02,
                "nb_commits": 12,
                "nb_additions": 13444,
                "nb_deletions": 24422,
                "largest_commits": [
                    {
                        "author": {
                            "name": "Johannes",
                            "email": "[email protected]"
                        },
                        "title": "adds a new cool feature",
                        "ref": "abcdef"
                    },
                    {
                        "author": {
                            "name": "Muha",
                            "email": "[email protected]"
                        },
                        "title": "fixing fubar to foo/bar",
                        "ref": "123456"
                    },
                ],
                "top_contributors": [
                    {
                        "name": "Johannes",
                        "email": "[email protected]",
                        "nbCommits": 123,
                        "nbAdditions": 444,
                        "nbDeletions": 445
                    },
                ],
                "algorithm_changed": false,
                "_links": {
                    "self": {
                        "href": "\/api\/repositories\/g\/scrutinizer-ci\/report1\/reports\/2014-06-24"
                    },
                    "repository": {
                        "href": "\/api\/repositories\/g\/scrutinizer-ci\/report1"
                    }
                },
                "_embedded": {
                    "repository": {
                        "type": "g",
                        "created_at": "2017-07-07T16:11:25+0000",
                        "private": false,
                        "default_branch": "master",
                        "applications": {
                            "master": {
                                "build_status": {
                                    "status": "unknown"
                                }
                            },
                            "foo": {
                                "build_status": {
                                    "status": "unknown"
                                }
                            }
                        },
                        "development_report_settings": {
                            "enabled": true,
                            "weekday": 1,
                            "hour": 8,
                            "timezone": "UTC"
                        },
                        "branch_settings": {
                            "tracked_branches": []
                        },
                        "login": "scrutinizer-ci",
                        "name": "report1",
                        "_links": {
                            "self": {
                                "href": "\/api\/repositories\/g\/scrutinizer-ci\/report1"
                            }
                        },
                        "_embedded": {
                            "organization": {
                                "slug": "scrutinizer",
                                "name": "Scrutinizer Org"
                            }
                        }
                    }
                }
            }
        ]
    }
}

Repositories

Repository Details

Retrieves details about a repository.

Endpoints

GitHub:GET repositories/g/{login}/{name}
Bitbucket:GET repositories/b/{username}/{repoSlug}
GitLab:GET repositories/gl/{instanceSlug}/{namespace}/{name}
Plain Git:GET repositories/gp/{slug}

Sample Response

{
    "type": "g",
    "created_at": "2014-02-08T16:25:28+0000",
    "private": false,
    "default_branch": "master",
    "applications": {
        "master": {
            "index": {
                "source_reference": "c1466bf9f01a4c9190f7584c46f5c31b96da3291",
                "id": 9,
                "branch_reference": "master",
                "created_at": "2014-02-08T16:25:33+0000",
                "outdated": false,
                "_links": {
                    "issues": {
                        "href": "\/api\/repositories\/g\/your-login\/your-repo\/indices\/9\/issues"
                    }
                },
                "_embedded": {
                    "project": {
                        "type": "system",
                        "identifier": "",
                        "metric_values": {
                            "scrutinizer.quality": 8.5,
                            "scrutinizer.nb_operations.very_good": 3,
                            "scrutinizer.nb_operations.good": 2,
                            "scrutinizer.nb_operations.satisfactory": 6,
                            "scrutinizer.nb_operations.pass": 3,
                            "scrutinizer.nb_operations.critical": 9,
                            "scrutinizer.weight.very_good": 0.090909090909091,
                            "scrutinizer.weight.good": 0.060606060606061,
                            "scrutinizer.weight.satisfactory": 0.18181818181818,
                            "scrutinizer.weight.pass": 0.090909090909091,
                            "scrutinizer.weight.critical": 0.27272727272727,
                            "scrutinizer.nb_classes": 1,
                            "scrutinizer.nb_classes.very_good": 0,
                            "scrutinizer.nb_classes.good": 0,
                            "scrutinizer.nb_classes.satisfactory": 0,
                            "scrutinizer.nb_classes.pass": 1,
                            "scrutinizer.nb_classes.critical": 0,
                            "scrutinizer.test_coverage": 0.384848
                        }
                    }
                }
            }
        }
    },
    "development_report_settings": {
        "enabled": true,
        "weekday": 1,
        "hour": 8,
        "timezone": "UTC"
    },
    "branch_settings": {
        "tracked_branches": [

        ]
    },
    "login": "your-login",
    "name": "your-repo",
    "_links": {
        "self": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo"
        }
    }
}

Repository Issues

If you would like to retrieve the list of issues for a branch of your repository, you can first retrieve the repository details.

The repository details contain a reference to the latest index for each branch under the applications key. You can then use the id of that index to query for issues.

Adding GitHub Repository

Endpoint

POST repositories/g

Request Attributes

Name Type Description
name string Required. The repository?s name, for example scrutinizer-ci/web.
organization string The organization?s slug that this repository should be associated with.
config string The repository?s initial configuration as Yaml.
global_config string The UUID of a global configuration that should be used by the repository. For an organization repository, see organization configs, otherwise a use a user config.

Status Codes

201:On success when the repository was created.

Sample Request Body

{
    "name": "scrutinizer-ci/web",
    "organization": "scrutinizer",
    "config": "build: true\n\nchecks:\n    php:\n        code_rating: true\n",
    "global_config": "914f3a52-6e9e-47a0-a798-0d98d2b5ad0b"
}

Adding Bitbucket Repository

Endpoint

POST repositories/b

Request Attributes

Name Type Description
name string Required. The repository?s name, for example scrutinizer-ci/web.
organization string The organization?s slug that this repository should be associated with.
config string The repository?s initial configuration as Yaml.
global_config string The UUID of a global configuration that should be used by the repository. For an organization repository, see organization configs, otherwise a use a user config.

Status Codes

201:On success when the repository was created.

Sample Request Body

{
    "name": "scrutinizer-ci/web",
    "organization": "scrutinizer",
    "config": "build: true\n\nchecks:\n    php:\n        code_rating: true\n",
    "global_config": "914f3a52-6e9e-47a0-a798-0d98d2b5ad0b"
}

Adding Plain Git Repository

Endpoint

POST repositories/gp

Request Attributes

Name Type Description
name string Required. The repository?s name, for example scrutinizer-ci-web.
git_url string Required. The repository?s URL, for example git@my-host.com:scrutinizer-ci-web.git
ssh_key string Required. The SSH private key that should be used for cloning.
organization string The organization?s slug that this repository should be associated with.
config string The repository?s initial configuration as Yaml.
global_config string The UUID of a global configuration that should be used by the repository. For an organization repository, see organization configs, otherwise a use a user config.

Status Codes

201:On success when the repository was created.

Sample Request Body

{
    "name": "scrutinizer-ci/web",
    "git_url": "[email protected]:scrutinizer-ci-web.git",
    "organization": "scrutinizer",
    "ssh_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAsqWrC\/CnORBIDk6juou\/HUWRzjhcqVOsRUmWxw8afwW6NMRJ\n312p8mZ39yvTdkwodksiq1TFTq5EGgeOESiMR125DeG2nkQ\/LPLj1qPGLoFQgzFdC\nL9d2CEMOyiKCRHOWqVvi\/jvQnSwrElgU1KN0bkHiAKv7dwqOmJjbT+bLrPUgoC7b\nFCYxIDFRrmgezOEGF0E82YT+ixFk3xDkyUvdMCEVX0y8xe2W02xtH5d9mklEWbMD\nRxSavUWGI9JKPYduGr\/QOluLJD1kzXc2kZB0IWA\/PLtncFhL3OSwqsdX6dUz1nVQ\n9b0nq\/roNwdrf\/iQeBs9RQ0Zm4q9ZcKsuF3DFwIDAQABAoIBAQCeWDtw\/OCrsqqA\nSO+0xHMkVeqz179CErkqPNzZGakJl6EBbk5wHowpH+wLeJvO\/kpS2Nta1jrsYkJb\nVLeIIudfT0Y0MzWIXXBuJR8RnO9+r7LWjC1NTHQBRLbSMZ43YCDVgm2DnK7+8QxI\nWSw1gaAMrnbM06OzUvcriKkzfEVhyfPI563JzYEEm2zdZJVvGKxlNZmrJy2vesBf\nWAwImZrrN3PNmHmM1Hl\/RQLThdc5kztH77uYova+34v3kqscnOVjpTsWIZLriI4B\nT1Rb145OYjibxhU2xq0SucLHSr3\/Q2T3H5tv9TTwiutGAl06eszJj\/T8eThOcsKd\n3ds8A8wJAoGBAOfFNt+pxtZrcssYQnQsfpk5QXYNDRShivLsN5g\/JFQi+BoaZieg\nX8kUeodTbPlHwYekWHtIgivtEyUUdeyuZUupNbfPaMScybrWogsjyqf+wUTkmvie\nGi306hfbeMWExyYB663mMoF9AVhtr6GbXjFZL+aPVL3h44K62GhI6LR1AoGBAMVS\nvH1Gb2avEOd+Vp\/+ZjDsW3Tgo9tf+tXfi099UX8vUl4r6D9xG6I7Y25fmtFlJd3P\nErCbpRlvw+inrZ6I\/osZawpLyahd7luRcExvy7zICn3qidX9j1EofV+SMBvzjNNe\nxnjd4jaAatqgg20PP+3nDpDroEQa4F7VWAqmpXfbAoGAQmh1kpx4xpM+7wZidBsT\nox+OrB6NMu4efABG5a6h4CGs6P3La2s+RsVBXmj+\/mYbA5yJZbme4qspIyS7rTdC\n+uze4W3iXQN3obtB7uMwe\/Y4tl6yMK5MXgKg2HkgH6gtkie24EPzkLqamhXDjxCP\naqBdYziKVWXV5G1Y+Hh7hMkCgYBkJPpupgmx1pXAtzjlmGpq1\/oOllfy5YJbe0mr\nvRFYeD7YdnY3hIMe0f9DrBfZv\/j42rhEk6m2ACgwcrFF7YcqN2tA3XfqEEoBhQ22\nbWK8W9YfU6JCzZ4n9WGz2HC8Lt5BBC+8dffx6zjP3nj1J7EtX3\/gAwXiqrVGzAYT\n2cHO0wKBgQCJkDb01B6iL\/fkIQ0XiDuoSaGH5iIH91qAvDVLM0NEsT1DUjkUrejw\n+dP8u2J83OYmXaKnkuy6idj8+8kKDSHy31Rn78HNwlpkAurifAdTuhCE4cdGkv0w\njjWiiNRwTB1whdSfa6tdpwdPGYYFuNkJ\/sPUIx0FjSRqMhsapRYcsw==\n-----END RSA PRIVATE KEY-----\n",
    "config": "build: true\n\nchecks:\n    php:\n        code_rating: true\n",
    "global_config": "914f3a52-6e9e-47a0-a798-0d98d2b5ad0b"
}

Inspections

The Inspection Object

The Inspection object ties together all the data belonging to a specific inspection of your source code such as the progress, the progress log and any result information of the analyses. The Inspection object itself does not contain the analysis results, but only references to Index objects which contain all the results for a specific version of your source code.

Notable Fields

state:

Available states: new, preparing, pending, in_progress, failed, completed, timed_out, canceled

head_index:

The head index is always available and contains all the information of the version of your source code which was inspected.

base_index:

The base index refers to the latest version which was inspected before this inspection. It is only available for incremental inspections.

index_diff:

The diff contains the changes between the head and base indices. It is only available for incremental inspections.

build:

Contains information around the build of this code version.

status

The build?s status. Possible values:

  • unknown: no tests were executed and no build failure conditions were given
  • passed: all tests passed, and no failure condition matched
  • failed: at least one test failed or one failure condition matched
  • error: something went wrong during the inspection, or test set-up
  • pending: If you are using an external continuous integration service, and we do not know its build status, yet.
details Provides additional information if the build failed such as the failed build conditions.
metadata:

Some additional background information around the inspection:

title A human-readable title for the inspection.
source_reference A reference for the revision of the source code that was inspected.
branch The branch which was inspected.

Listing Inspections

Retrieves a list of inspections for your repository. By default, the most recent inspections are listed first.

Endpoints

GitHub:GET repositories/g/{login}/{name}/inspections
Bitbucket:GET repositories/b/{username}/{repoSlug}/inspections
GitLab:GET repositories/gl/{instanceSlug}/{namespace}/{name}/inspections
Plain Git:GET repositories/gp/{slug}/inspections

Parameters

sort_field:Allows you to specify the field used for sorting. Available fields: created_at and finished_at (defaults to created_at).
sort_order:Allows you to specify the order used for sorting (asc or desc). Defaults to desc.
page:The page which you want to view (1-based). Defaults to 1.
per_page:The number of inspections which should be listed per page (minimum: 1 - maximum: 100). Defaults to 20.

Sample Response

{
    "page": 1,
    "limit": 1,
    "sort_field": "created_at",
    "sort_order": "desc",
    "_links": {
        "self": {
            "href": "\/api\/repositories\/g\/your-name\/your-repo\/inspections?page=1&per_page=1"
        },
        "first": {
            "href": "\/api\/repositories\/g\/your-name\/your-repo\/inspections?page=1&per_page=1"
        },
        "next": {
            "href": "\/api\/repositories\/g\/your-name\/your-repo\/inspections?page=2&per_page=1"
        }
    },
    "_embedded": {
        "inspections": [
            {
                "uuid": "914f3a52-6e9e-47a0-a798-0d98d2b5ad0b",
                "state": "completed",
                "created_at": "2014-01-20T13:30:01+0000",
                "started_at": "2014-01-20T13:30:06+0000",
                "finished_at": "2014-01-20T13:37:47+0000",
                "_links": {
                    "self": {
                        "href": "\/api\/repositories\/g\/your-name\/your-repo\/inspections\/914f3a52-6e9e-47a0-a798-0d98d2b5ad0b"
                    },
                }
            }
        ]
    }
}

Inspection Details

Retrieves details about an inspection.

Endpoints

GitHub:GET repositories/g/{login}/{name}/inspections/{uuid}
Bitbucket:GET repositories/b/{username}/{repoSlug}/inspections/{uuid}
GitLab:GET repositories/gl/{instanceSlug}/{namespace}/{name}/inspections/{uuid}
Plain Git:GET repositories/gp/{slug}/inspections/{uuid}

Sample Response

{
    "uuid": "914f3a52-6e9e-47a0-a798-0d98d2b5ad0b",
    "state": "completed",
    "created_at": "2014-01-20T13:30:01+0000",
    "started_at": "2014-01-20T13:30:06+0000",
    "finished_at": "2014-01-20T13:37:47+0000",
    "build": {
        "status": "failed",
        "details": {
            "analysis": {
                "failures": [
                    "classes.rating(<= D).new.exists"
                ],
                "status": "failed"
            },
            "tests": {
                "status": "failed"
            }
        }
    },
    "_links": {
        "self": {
            "href": "\/api\/repositories\/g\/your-name\/your-repo\/inspections\/914f3a52-6e9e-47a0-a798-0d98d2b5ad0b"
        },
        "repository": {
            "href": "\/api\/repositories\/g\/your-name\/your-repo"
        }
    },
    "_embedded": {
        "repository": {
            "type": "g",
            "created_at": "2012-08-23T15:52:03+0000",
            "private": false,
            "default_branch": "master",
            "development_report_settings": {
                "enabled": true,
                "interval": "P1W",
                "weekday": 1,
                "hour": 8,
                "timezone": "UTC"
            },
            "branch_settings": {
                "tracked_branches": [
                    "master"
                ]
            },
            "login": "your-name",
            "name": "your-repo",
            "_links": {
                "self": {
                    "href": "\/api\/repositories\/g\/your-name\/your-repo"
                }
            }
        },
        "head_index": {
            "source_reference": "f44eefc065e980d5fa2f1be5c4fd944f41855a6b",
            "id": 18525,
            "branch_reference": "master",
            "outdated": false,
            "_embedded": {
                "project": {
                    "type": "system",
                    "identifier": "",
                    "metric_values": {
                        "scrutinizer.test_coverage": 0.84782608695652,
                        "scrutinizer.quality": 9.5998917162967,
                        "scrutinizer.nb_issues": 11,
                        "scrutinizer.nb_ignored_issues": 0
                    }
                }
            }
        },
        "base_index": {
            "source_reference": "3cb8bd396b961c156e964e3f58c9ad5206acf0a0",
            "id": 18486,
            "branch_reference": "master",
            "outdated": false,
            "_embedded": {
                "project": {
                    "type": "system",
                    "identifier": "",
                    "metric_values": [

                    ]
                }
            }
        },
        "index_diff": {
            "nb_new_issues": 11,
            "nb_common_issues": 0,
            "nb_fixed_issues": 6,
            "nb_added_code_elements": 141,
            "nb_common_code_elements": 0,
            "nb_changed_code_elements": 1,
            "nb_removed_code_elements": 0
        }
    }
}
Note: Some information might only be available after an inspection has finished successfully.

Inspection Artifacts

Retrieves details about the artifacts of an inspection.

Endpoints

GitHub:GET repositories/g/{login}/{name}/inspections/{uuid}/artifacts
Bitbucket:GET repositories/b/{username}/{repoSlug}/inspections/{uuid}/artifacts
GitLab:GET repositories/gl/{instanceSlug}/{namespace}/{name}/inspections/{uuid}/artifacts
Plain Git:GET repositories/gp/{slug}/inspections/{uuid}/artifacts

Sample Response

{
    "node-1": {
        "foo-bar.log": {
            "download_url": "https:\/\/download.domain.com\/node-1\/foo-bar.log",
            "expired": false
        },
        "selenium.log": {
            "download_url": "https:\/\/download.domain.com\/node-1\/selenium.log",
            "expired": true
        }
    },
    "node-2": {
        "foo-bar.log": {
            "download_url": "https:\/\/download.domain.com\/node-2\/foo-bar.log",
            "expired": true
        }
    }
}
Note: If the artifact has been purged from our systems already, expired is set to true. You will want to check this before attempting to download, or otherwise handle 404 errors gracefully.

Inspection Issues

If you would like to retrieve the list of issues for a specific inspection, you can first retrieve the inspection details.

The inspection details contain the reference to the head_index. You can then use the id of that index to query for issues.

Creating Inspections

Creates a new inspection for your repository.

Endpoints

GitHub:POST repositories/g/{login}/{name}/inspections
Bitbucket:POST repositories/b/{username}/{repoSlug}/inspections
GtiLab:POST repositories/gl/{instanceSlug}/{namespace}/{name}/inspections
Plain Git:POST repositories/gp/{slug}/inspections

Parameters

Name Type Description
branch string Required. The branch which should be inspected.
source_reference string The exact source reference which should be inspected. If not given, this defaults to the latest version in the branch.
title string A human readable title for the inspection. If not given, this defaults to the title of the commit message.
config string A YAML config which should be used just for this inspection. If not given, your regular configuration is used.

Return Codes

201:On success. The Location header contains a link to the inspection resource.
400:If one of the parameters contains invalid input.

Sample Response

See inspection details.

Indices

The Index Object

The Index object holds a reference to all the data that is collected for a specific version of your source code such as issues, metrics, files, code coverage, or any other information related to your source code.

Notable Fields

source_reference:
 The version of your source code (sha) which the data is associated with.
outdated:If you run multiple inspections on the same version (with different configuration for example), all Index objects except the most recent one will be set to outdated.
branch_reference:
 The branch this Index belongs to. This might not be available if for example the Index represents information which is not part of any branch (like pull requests f.e.).

Index Details

Retrieves details about an Index.

Endpoints

GitHub:GET repositories/g/{login}/{name}/indices/{idOrSourceReference}
Bitbucket:GET repositories/b/{username}/{repoSlug}/indices/{idOrSourceReference}
GitLab:GET repositories/gl/{instanceSlug}/{namespace}/{name}/indices/{idOrSourceReference}
Plain Git:GET repositories/gp/{slug}/indices/{idOrSourceReference}

Sample Response

{
    "source_reference": "c1466bf9f01a4c9190f7584c46f5c31b96da3291",
    "id": 9,
    "branch_reference": "master",
    "created_at": "2014-02-08T16:25:33+0000",
    "outdated": false,
    "_links": {
        "issues": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo\/indices\/9\/issues"
        }
    },
    "_embedded": {
        "project": {
            "type": "system",
            "identifier": "",
            "metric_values": {
                "scrutinizer.quality": 8.5,
                "scrutinizer.nb_operations.very_good": 3,
                "scrutinizer.nb_operations.good": 2,
                "scrutinizer.nb_operations.satisfactory": 6,
                "scrutinizer.nb_operations.pass": 3,
                "scrutinizer.nb_operations.critical": 9,
                "scrutinizer.weight.very_good": 0.090909090909091,
                "scrutinizer.weight.good": 0.060606060606061,
                "scrutinizer.weight.satisfactory": 0.18181818181818,
                "scrutinizer.weight.pass": 0.090909090909091,
                "scrutinizer.weight.critical": 0.27272727272727,
                "scrutinizer.nb_classes": 1,
                "scrutinizer.nb_classes.very_good": 0,
                "scrutinizer.nb_classes.good": 0,
                "scrutinizer.nb_classes.satisfactory": 0,
                "scrutinizer.nb_classes.pass": 1,
                "scrutinizer.nb_classes.critical": 0,
                "scrutinizer.test_coverage": 0.384848
            }
        }
    }
}

Index Issues

Retrieves a list of issues for a specific version of your source code.

Endpoints

GitHub:GET repositories/g/{login}/{name}/indices/{idOrSourceReference}/issues
Bitbucket:GET repositories/b/{username}/{repoSlug}/indices/{idOrSourceReference}/issues
GitLab:GET repositories/gl/{instanceSlug}/{namespace}/{name}/indices/{idOrSourceReference}/issues
Plain Git:GET repositories/gp/{slug}/indices/{idOrSourceReference}/issues

Parameters

page:The page which you want to view (1-based). Defaults to 1.
per_page:The number of issues which should be listed per page (minimum: 1 - maximum: 100). Defaults to 50.
labels:An array of labels for filtering the list of issues (to be passed like ?labels[]=label1&labels[]=label2). Available labels: complexity, unused-code, coding-style, duplication, security, comprehensibility, documentation, naming, bug, performance, deprecated-code, configuration, compatibility, debugging-code
severities:An array of severities for filtering the list of issues (to be passed like ?severities[]=major&severities[]=minor). Available severities: critical, major, minor, informational, unknown
languages:php, javascript, ruby, python, java

Sample Response

{
    "page": 1,
    "limit": 1,
    "labels": [
        "coding-style"
    ],
    "severities": [

    ],
    "_links": {
        "self": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo\/indices\/9\/issues?page=1&per_page=1"
        },
        "first": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo\/indices\/9\/issues?page=1&per_page=1"
        },
        "next": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo\/indices\/9\/issues?page=2&per_page=1"
        }
    },
    "_embedded": {
        "issues": [
            {
                "path": "src\/Scrutinizer\/Test.php",
                "line": 2,
                "message_id": "class.not_good",
                "message": "This is not so good.",
                "message_parameters": [

                ],
                "severity": "informational",
                "labels": [
                    "complexity",
                    "coding-style"
                ],
                "issue_identifier": "abcdef1234567890"
            }
        ]
    }
}

Reports

Tip: If you would like to retrieve the latest reports for each repository in your organization, see organization reports.

Listing Reports

Endpoints

GitHub:GET repositories/g/{login}/{name}/reports
Bitbucket:GET repositories/b/{username}/{repoSlug}/reports
Gitlab:GET repositories/gl/{instanceSlug}/{namespace}/{name}/reports
Plain Git:GET repositories/gp/{slug}/reports

Parameters

sort_field:Allows you to specify the field used for sorting. Available fields: created_at (defaults to created_at).
sort_order:Allows you to specify the order used for sorting (asc or desc). Defaults to desc.
page:The page which you want to view (1-based). Defaults to 1.
per_page:The number of inspections which should be listed per page (minimum: 1 - maximum: 100). Defaults to 20.

Sample Response

{
    "page": 1,
    "limit": 20,
    "sort_field": "created_at",
    "sort_order": "desc",
    "_links": {
        "self": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo\/reports?page=1&per_page=20"
        },
        "first": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo\/reports?page=1&per_page=20"
        },
        "next": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo\/reports?page=2&per_page=20"
        }
    },
    "_embedded": {
        "reports": [
            {
                "date": "2013-12-02",
                "created_at": "2013-12-02T10:20:51+0000",
                "start_date": "2013-11-24T23:00:00+0000",
                "end_date": "2013-12-01T22:59:59+0000",
                "branch_reference": "master",
                "base_source_reference": "4433e80a0f5f4f9548129940d781d26516ab0ef8",
                "head_source_reference": "21ee96f2c4f20223e48b88e2d0fd34a196d17196",
                "_links": {
                    "self": {
                        "href": "\/api\/repositories\/g\/your-login\/your-repo\/reports\/2013-12-02"
                    }
                }
            }
        ]
    }
}

Report Details

Retrieves details about a report.

Endpoints

GitHub:GET repositories/g/{login}/{name}/reports/{date}
Bitbucket:GET repositories/b/{username}/{repoSlug}/reports/{date}
GitLab:GET repositories/gl/{instanceSlug}/{namespace}/{name}/reports/{date}
Plain Git:GET repositories/gp/{slug}/reports/{date}

Sample Response

{
    "date": "2013-12-02",
    "created_at": "2013-12-02T10:20:51+0000",
    "start_date": "2013-11-24T23:00:00+0000",
    "end_date": "2013-12-01T22:59:59+0000",
    "branch_reference": "master",
    "base_source_reference": "4433e80a0f5f4f9548129940d781d26516ab0ef8",
    "head_source_reference": "21ee96f2c4f20223e48b88e2d0fd34a196d17196",
    "quality_score": 8.143449482422,
    "quality_score_change": 0.0031622364272987,
    "quality_distribution": {
        "weights": {
            "very_good": 481.97000000001,
            "good": 68.69,
            "satisfactory": 22.77,
            "pass": 38.76,
            "critical": 26.16
        }
    },
    "nb_alerts": 0,
    "nb_alerts_change": 0,
    "nb_issues": 120,
    "nb_issues_change": 3,
    "test_coverage_change": 0,
    "nb_commits": 43,
    "nb_additions": 4603,
    "nb_deletions": 960,
    "largest_commits": [
        {
            "author": {
                "name": "Foo Bar",
                "email": "[email protected]"
            },
            "title": "adds foo bar",
            "ref": "6033140f7f05355fa83c0afc871f6fdc906aced9"
        },
        {
            "author": {
                "name": "Foo Bar",
                "email": "[email protected]"
            },
            "title": "fixes foo bar",
            "ref": "7dbd58039accb20f3dba1d81aa73a0f117022e8f"
        }
    ],
    "top_contributors": [
        {
            "name": "Foo Bar",
            "email": "[email protected]",
            "nbCommits": 43,
            "nbAdditions": 4603,
            "nbDeletions": 960
        }
    ],
    "algorithm_changed": false,
    "_links": {
        "self": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo\/reports\/2013-12-02"
        },
        "repository": {
            "href": "\/api\/repositories\/g\/your-login\/your-repo"
        }
    },
    "_embedded": {
        "repository": {
            "type": "g",
            "created_at": "2013-08-06T07:17:19+0000",
            "private": true,
            "default_branch": "master",
            "development_report_settings": {
                "enabled": true,
                "weekday": 1,
                "hour": 8,
                "timezone": "Europe\/Berlin"
            },
            "branch_settings": {
                "tracked_branches": [
                    "master"
                ]
            },
            "login": "your-login",
            "name": "your-repo",
            "_links": {
                "self": {
                    "href": "\/api\/repositories\/g\/your-login\/your-repo"
                }
            }
        }
    }
}

Users

Listing Accessible Repositories

This endpoint shows all the repositories that are accessible by the authenticated user.

Endpoint

GET user/repositories

Parameters

page:The page which you want to view (1-based). Defaults to 1.
per_page:The number of inspections which should be listed per page (minimum: 1 - maximum: 100). Defaults to 20.

Sample Response

{
    "page": 1,
    "limit": 2,
    "_links": {
        "self": {
            "href": "\/api\/user\/repositories?page=1&per_page=2"
        },
        "first": {
            "href": "\/api\/user\/repositories?page=1&per_page=2"
        },
        "next": {
            "href": "\/api\/user\/repositories?page=2&per_page=2"
        }
    },
    "_embedded": {
        "repositories": [
            {
                "type": "b",
                "created_at": "2015-01-25T21:08:14+0000",
                "username": "scrutinizer-ci",
                "repo_slug": "bitbucket-private",
                "_links": {
                    "self": {
                        "href": "\/api\/repositories\/b\/scrutinizer-ci\/bitbucket-private"
                    }
                }
            },
            {
                "type": "b",
                "created_at": "2015-01-25T21:08:14+0000",
                "username": "scrutinizer-test",
                "repo_slug": "metadata",
                "_links": {
                    "self": {
                        "href": "\/api\/repositories\/b\/scrutinizer-test\/metadata"
                    }
                }
            }
        ]
    }
}

Viewing User Configs

Endpoint

GET user/configs

Sample Response

{
    "page": 1,
    "limit": 20,
    "_links": {
        "self": {
            "href": "\/app_test.php\/api\/user\/configs?page=1&per_page=20"
        },
        "first": {
            "href": "\/app_test.php\/api\/user\/configs?page=1&per_page=20"
        },
        "next": {
            "href": "\/app_test.php\/api\/user\/configs?page=2&per_page=20"
        }
    },
    "_embedded": {
        "configs": [
            {
                "created_at": "2015-01-26T11:55:30+0000",
                "modified_at": "2015-01-26T11:55:30+0000",
                "name": "Foo",
                "uuid": "011a9862-90c6-47fb-8ae8-6f17e302a13c",
                "_links": {
                    "self": {
                        "href": "\/app_test.php\/api\/user\/configs\/011a9862-90c6-47fb-8ae8-6f17e302a13c"
                    }
                }
            }
        ]
    }
}

Webhooks

Every repository on Scrutinizer has the option to communicate with a web server during the lifecycle of an inspection. These ?webhooks? can be used to update an external issue tracker, or trigger other external processes to optimally integrate Scrutinizer into your development workflow.

Events & Payloads

Every hook is triggered for every event. The payloads consist of json-encoded data that mirrors the payloads of the remaining API. The available events and corresponding payloads are:

Name Description Payload
inspection.created Any time an inspection is created. Inspection
inspection.completed Any time an inspection is completed and results are available. Inspection
inspection.canceled Any time an inspection is aborted. Inspection
inspection.failed Any time an inspection has failed with no results. Inspection
Note: Please make sure that your endpoint handles unknown events gracefully. We consider adding new events a backwards-compatible API change.

Delivery headers

HTTP requests made to your server will contain these special headers:

Header Description
X-Scrutinizer-Event Name of the event that triggered this request.
X-Scrutinizer-Signature HMAC hex digest of the concatenation of event name and payload, using the hook?s secret as key and the sha1 algorithm.

Verifying Message Authenticity

If you want to make sure messages were sent by Scrutinizer before processing them, there are two ways to accomplish this:

1. Using the sent signature and your hook?s secret

Scrutinizer sends a signature of the payload, a HMAC hex digest, as request header to your server. You can use this signature to verify the message?s authenticity.

Below you find some sample code for how to accomplish this:

// You find the $secret on the "Service Hooks" page of your repository.
// Each hook has its own secret which should be kept private at all times.
$signature = hash_hmac('sha1', $request->getHeader('X-Scrutinizer-Event').$request->getContent(), $secret);

if ($request->getHeader('X-Scrutinizer-Signature') !== $signature) {
    throw new RuntimeException('Invalid Signature');
}
Tip: When you are comparing the sent signature against your computed signature, you ideally want to use a constant time comparison algorithm to avoid being susceptible to timing attacks.

2. Using the sender IP

As an alternative, to verifying the signature, you can also compare the sender IP against our published IP blocks.