Getting Started with the Credo AI API

The Credo AI API provides robust access to a wide range of resources for managing AI use cases, models, stakeholders, policies, risk scenarios, and more. It enables seamless integration with external systems, following RESTful principles and supporting the JSON API protocol.

Knowledge Prerequisites

To get the most out of this guide, users should ideally have:

A working knowledge of Credo AI's core components and governance workflows.
Experience with API authentication (e.g., using tokens or OAuth).
Basic skills in making HTTP requests (GET, POST, PUT, DELETE) and handling JSON responses.

For those new to the Credo AI platform, we recommend starting with the platform’s core concepts before diving into this API guide.

URL

For Saas users, base URL is https://api.credo.ai/

For Self Hosted users, base URL will be the Credo AI URL used in configuration

Content Type

All API requests and responses use the application/vnd.api+json content type.

Pagination

If your response includes more results than can be returned in a single request, the API will paginate the results.

You can control pagination using the page[after] or page[before] parameters.
The token for page before and after are returned in the meta data of the response
To paginate, you must also use sort=inserted_at as a parameter to ensure that the same results are displayed in the same page and not returned again in future/previous pages
- Without sorting, the data could change each time you move from one page to the next, disrupting the user experience

Metadata

after - the token for the page[after] parameter

before - the token for the page[before] parameter

total_count - the total number of use cases returned in the API response.

Include Option

You can use the include parameter when loading a resource that contains ids referencing other entities. It allows you to retrieve related data. However, if there is no established relationship between the entities, include will not work. For example, you can load use cases that include models using include=models

GET /use_cases/:uid/controls?include=models

The table below shows other include options

API Resource Type	Include Options
`use_cases`	`models, policy_packs, questionnaires, risk_scenarios, stakeholders, vendor_links, vendors, custom_fields`
`use_case_risk_scenarios`	`risk_control_links, risk_scenario`
`use_case_review_actions`	`reply_thread, review, task, use_case, user`
`use_case_reviews`	`actions, snapshot, tasks, use_case, user`
`use_case_threads`	`comments, parent_comment, user`
`use_case_stakeholders`	`team, user`
`use_case_vendor_links`	`vendor`
`vendors`	`questionnaires, use_case_links, use_cases, user`
`teams`	`members, memberships`
`users`	`setting`

Filters

Allow users to filter results based on specific criteria. For example:

GET /use_cases?filter[name]=AI%20Use%20Case

Sorting

Users can sort the data based on attributes like creation date or name:

GET /use_cases?sort=inserted_at

Error handling

The Credo AI API adheres to standard RESTful error-handling practices, utilizing HTTP status codes to indicate the outcome of API requests. Common status codes include:

200 OK: The request was successful, and the server returned the requested data.
400 Bad Request: The server could not process the request due to client-side errors, such as malformed syntax or invalid parameters.
401 Unauthorized: Authentication is required, and the client has failed to provide valid credentials.
403 Forbidden: The client authenticated successfully but does not have permission to access the requested resource.
422 Invalid content: The server understands the request, but it cannot process it due to semantic errors in the request payload
404 Not Found: The requested resource could not be found on the server.
500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.

In addition to these status codes, the API responses typically include a JSON object with details about the error, such as an error code, message, and possibly a more detailed description. This structured approach allows developers to programmatically handle errors and implement appropriate fallback mechanisms.

Breaking Changes

Credo AI reserves the right to release breaking changes to our API endpoints for the sake of improving our product. If we do release a breaking change, we will 1) add a deprecation notice to release notes at least 1 minor or major release ahead of the change, and 2) send a detailed migration guide to all customers.