Cobrainer Platform API (1.166.0)

Before you start using the Talent API, ensure that you have the following prerequisites in place:

• User credentials: To access the Talent API, you'll need a valid access token generated using your user credentials. If you don't have one, please contact our support team to obtain your user credentials.

• Development Environment: Set up your development environment with the required tools and libraries to make API calls. The Talent API is compatible with a variety of programming languages and frameworks, allowing you flexibility in your implementation.

• Understanding of REST APIs: Familiarize yourself with the fundamentals of REST APIs. This will help you understand how to structure your requests and handle responses effectively.

The Talent API documentation is divided into several sections, each addressing different aspects of API usage. Here's a brief overview of each section:

• Authorization: This section provides detailed information about the authentication process and guides you on how to get and use the access token in requests to authorize your access to the Talent API.

• Use-cases: The Use-cases section provides an in-depth look at how the Talent API's capabilities and functionalities can be applied. It details key use-cases such as Skills, Users, Recruiting, Upskilling, Job Architecture, and AI agent access via MCP. This section serves as a comprehensive guide to understanding the API's core functionalities.

• Error Handling: The Error Handling section describes the different types of error responses that can be returned by the Talent API. It offers guidance on how to interpret and handle these errors in your application, ensuring that you can gracefully handle any unexpected situations that may arise during API interactions.

• Rate Limiting: The Rate Limiting section explains the rate limits imposed on API calls to ensure fair usage and optimal performance. It provides you with details on the number of requests allowed within a specific timeframe, helping you understand how to manage and handle rate limit-related scenarios effectively.

• Support: In the Support section, you will find valuable information on how to seek assistance and get the support you need. Whether you have questions, encounter difficulties, or require clarifications related to the Talent API, our team is readily available to provide prompt assistance and help you overcome any challenges you may face.

• API Reference: The API Reference section contains detailed information about each API endpoint supported by the Talent API. It includes comprehensive documentation on the request/response structure, required parameters, and possible responses for each endpoint. This section serves as a comprehensive guide for developers who are implementing the Talent API in their applications.

Download configuration guides, technical designs, and supporting files for integrating SAP SuccessFactors with Cobrainer.

SAP Learning

• Learning material

SAP Talent Intelligence Hub

• Configuration guide V2
• Technical design V2
• Configuration guide
• Technical design
• Delta document
• Integration Center definitions
• Integration Center scheduler

SAP SuccessFactors Job Profile Builder

• Configuration guide

If you are using an AI assistant or agent to work with the Talent API, point it at llms.txt. It provides a machine-friendly index of this documentation: links to the raw OpenAPI specification, the guide chapters as plain markdown, and the MCP servers with their tool catalog.

The Cobrainer REST APIs encompass several principles aimed at implementing standard RESTful practices on a large scale, ensuring consistent data modeling, and delivering a structured developer experience from start to finish.

Data Formats

Only the JSON format is supported for input and output. For all requests, the corresponding HTTP header should be set: Content-Type: application/json. Responses also contain this header.

All endpoints allow control over the language of the returned result. The HTTP Header Accept-Language: en-US or Accept-Language: de-DE should be set for this purpose.

Typical endpoints

For most entities, a set of typical endpoints is supported with some generic conventions.

• OPTIONS: /<entity> - returns a list of possible operations for the given entity. The response contains a list of available methods with path, attributes, and additional metadata. The response considers tenant configuration and requesting user permissions.

• GET: /<entity> - returns a list of all objects for the given entity. The response can be sorted and paginated. In this case, query parameters sort, page, size, and countOnly are accepted.

• POST: /<entity> - creates a new object for the given entity. The request accepts all fields for the entity. The response contains the created entity with ID. Field values in the response may differ from the request if the backend uses some defaults and validations.

• GET: /<entity>/{id} - reads a single object for the given entity. The response data may contain more values (including nested objects) than the responses returning a list of objects.

• PATCH: /<entity>/{id} - modifies a single object for the given entity. All request fields are optional; only values present in the request are replaced. To set an empty value for some attribute, null can be passed. The response contains the updated entity with ID.

• DELETE: /<entity>/{id} - deletes a single object for the given entity. No request body is required. The operation returns HTTP status 204 (NO-CONTENT) in case of successful deletion.

• GET: /<entity>/filter - returns a list of allowed filter fields with possible values for these fields.

• POST: /<entity>/filter - reads a list of objects for the given entity filtered by provided criteria. The request body has the following structure:

  {
     "paged": {
        "page": 0, // page number
        "size": 20, // page size,
        "countOnly": false // flag showing that only count is needed, not the real data
     },
     "sorted": {
        "fields": [
           // array of fields with sorting direction
        ]
     },
     "filter": {
        // filter fields and conditions are here
     }
  }
  

Talent API utilizes a Bearer JSON Web Token (JWT) authentication mechanism and alternatively API-Keys to secure access to its resources and services. The JWTs and API-Keys are tied to and only grant permissions for accessing functionality of a specific customer.

If both JWT and API-Key authentication is provided on API requests, only the API-Key authentication gets evaluated.

• User Authentication: To access the Talent API endpoint, users or services must first authenticate themselves using their credentials (e.g., username and password) in Cognito.
• Token Generation: Upon successful authentication, the application generates a Bearer JWT token. This token is associated with the authenticated user and contains relevant information, such as the user's ID, customer ID, roles, and any additional claims needed for authorization.
• Token Inclusion: To include the Bearer JWT token in a request, users must set the "Authorization" header with the value "Bearer" followed by the token itself.
• Authorization: Talent API verifies the token's authenticity and integrity. Once the token is successfully validated, the application checks the user's permissions and roles encoded within the token's payload. It verifies whether the user is authorized to access the requested resource or perform the desired action.
• Token Expiration and Renewal: Bearer JWT tokens have a limited lifespan defined by their expiration time claim. Once a token expires, the user must request a new token from the Cognito User Pool. This can be done through either re-authentication or by using a refresh token.

JWT Authentication code examples

Below, you can find code examples that support the described authentication flow.

Java

package com.cobrainer.authexample;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.RestTemplate;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;
import software.amazon.awssdk.services.cognitoidentityprovider.model.*;

import java.time.LocalDateTime;
import java.util.Map;

public class TalentClient {

    private final String clientId;
    private final String userName;
    private final String password;
    private final CognitoIdentityProviderClient client;

    private String token;
    private String tokenType;
    private LocalDateTime expiration;
    private String refreshToken;

    // client id assigned to the customer, username and password are required for authentication. 
    public TalentClient(String clientId, String userName, String password) {
        this.client = CognitoIdentityProviderClient.builder().region(Region.EU_CENTRAL_1).build();
        this.clientId = clientId;
        this.userName = userName;
        this.password = password;
        setToken(initiateAuth());
    }

    // Example method demonstrating using token for GET requests.
    public <T> T call(String uri, Class<T> clazz) {
        RestTemplate template = new RestTemplate();
        HttpEntity<String> entity = new HttpEntity<String>("parameters", authHeader());
        // Using exchange to set headers with GET request.
        ResponseEntity<T> response = template.exchange(uri, HttpMethod.GET, entity, clazz);
        return response.getBody();
    }

    // Generate Authorization header for the request.
    private HttpHeaders authHeader() {
        if (expiration.isBefore(LocalDateTime.now())) {
            // Refresh the token if it's expired.
            refresh();
        }
        HttpHeaders headers = new HttpHeaders();
        headers.add("Authorization", tokenType + " " + token);
        return headers;
    }

    // Authenticate and obtain the token.
    private AuthenticationResultType initiateAuth() {
        InitiateAuthResponse authResponse = client.initiateAuth(
                InitiateAuthRequest.builder()
                        .authFlow(AuthFlowType.USER_PASSWORD_AUTH)
                        .authParameters(Map.of("USERNAME", userName, "PASSWORD", password))
                        .clientId(clientId)
                        .build());
        if (authResponse.challengeName() == ChallengeNameType.NEW_PASSWORD_REQUIRED) {
            // For new user the password change may be requested.
            return client.respondToAuthChallenge(
                    RespondToAuthChallengeRequest.builder()
                            .clientId(clientId)
                            .challengeName(authResponse.challengeName())
                            .session(authResponse.session())
                            .challengeResponses(Map.of("USERNAME", userName, "NEW_PASSWORD", password))
                            .build()).authenticationResult();
        } else {
            // Processing of other challenges maybe required if they set for user pool. Skipping it in this example.
            return authResponse.authenticationResult();
        }
    }

    // Refresh ID token based on refreshToken.
    private void refresh() {
        setToken(client.initiateAuth(InitiateAuthRequest.builder()
                .authFlow(AuthFlowType.REFRESH_TOKEN_AUTH)
                .authParameters(Map.of("REFRESH_TOKEN", refreshToken))
                .clientId(clientId)
                .build()).authenticationResult());
    }

    private void setToken(AuthenticationResultType authResult) {
        token = authResult.idToken();
        tokenType = authResult.tokenType();
        expiration = LocalDateTime.now().plusSeconds(authResult.expiresIn());
        refreshToken = authResult.refreshToken();
    }
}

Python

import datetime as dt

import boto3
import requests
from requests.auth import AuthBase


class AWSTenantAuthV2(AuthBase):
    _session_info = {
        "expiration_date": "",
        "token_type": "",
        "id_token": "",
        "refresh_token": ""
    }

    # client id assigned to the customer, username and password are required for authentication. 
    def __init__(self, client_id, username, password):
        self._username = username
        self._password = password
        self._client_id = client_id
        self._client = boto3.client("cognito-idp", "eu-central-1")
        self._start_session()

    # Example method demonstrating using token for requests.
    def __call__(self, req: requests.Request, *args, **kwargs):
        if self._session_info["expiration_date"] < dt.datetime.now():
            self._refresh_id_token()
        req.headers["Authorization"] = f"{self._session_info['token_type']} {self._session_info['id_token']}"

    # Authenticate and obtain the token.
    def _start_session(self):
        response = self._client.initiate_auth(
            AuthFlow="USER_PASSWORD_AUTH",
            AuthParameters={
                "USERNAME": self._username,
                "PASSWORD": self._password,
            },
            ClientId=self._client_id
        )

        self._session_info = {
            "expiration_date": dt.datetime.now() + dt.timedelta(0, response["AuthenticationResult"]["ExpiresIn"]),
            "id_token": response["AuthenticationResult"]["IdToken"],
            "token_type": response["AuthenticationResult"]["TokenType"],
            "refresh_token": response["AuthenticationResult"]["RefreshToken"]
        }

    # Refresh ID token based on refreshToken.
    def _refresh_id_token(self):
        response = self._client.initiate_auth(
            AuthFlow="REFRESH_TOKEN_AUTH",
            AuthParameters={
                "REFRESH_TOKEN": self._session_info["refresh_token"]
            },
            ClientId=self._client_id
        )
        self._session_info.update({
            "expiration_date": dt.datetime.now() + dt.timedelta(0, response["AuthenticationResult"]["ExpiresIn"]),
            "id_token": response["AuthenticationResult"]["IdToken"],
            "token_type": response["AuthenticationResult"]["TokenType"]
        })

• API-Key Creation: To access the Talent API endpoint, a key needs to be created at the developer portal at (tbd). Keys are created with a specific expiry date/time and a specific set of permissions.
• API-Key Usage: The API-Key is transmitted as HTTP header X-API-Key on every request, e.g. the full HTTP header would look like X-API-Key: cb-ab12cd34ef56.... If the API-Key is invalid, expired or disabled, an appropriate status code 401 response is returned.
• API-Key Rotation: To rotate keys that are close to expiry, simply create a new API-Key in the developer portal and update your systems to use the new key, before the old key expires. After rotation is finished, the old key can be disabled or deleted.
• API-Key Deprecation: At any time, existing API-Keys may be disabled (with the option to enable them again) or deleted. Keys that are deleted are irrecoverably lost and can't be recreated, therefore it's reasonable to first disable and only later delete them when confident, that they are no longer used.

API-Key Authentication code examples

Below, you can find code examples that support the described API-Key authentication.

Java

package com.cobrainer.authexample;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.RestTemplate;

import java.time.LocalDateTime;
import java.util.Map;

public class TalentClient {
    private final String apiKey;

    // apiKey must be propagated to the client from a secure location. Never hard-code API-Keys!
    public TalentClient(String apiKey) {
        this.apiKey = apiKey;
    }

    // Example method demonstrating using token for GET requests.
    public <T> T call(String uri, Class<T> clazz) {
        RestTemplate template = new RestTemplate();
        HttpEntity<String> entity = new HttpEntity<String>("parameters", apiKeyHeader());
        // Using exchange to set headers with GET request.
        ResponseEntity<T> response = template.exchange(uri, HttpMethod.GET, entity, clazz);
        return response.getBody();
    }

    // Generate X-API-Key header for the request.
    private HttpHeaders apiKeyHeader() {
        HttpHeaders headers = new HttpHeaders();
        headers.add("X-API-Key", apiKey);
        return headers;
    }
}

The Talent API incorporates a range of key features that enhance the application's functionality and usability. These key features have been thoughtfully integrated into the API, ensuring a comprehensive talent management solution that caters to our users' distinct requirements. The following features are at the core of the Talent API, providing an exceptional user experience and empowering seamless talent management processes.

The Skills API offers various capabilities to cater to your skill-related needs. With this API, you can conduct skill searches using specific criteria, accurately detect skills from textual content, and seamlessly retrieve skills-related information. At the heart of the skill API lies a skill data model that governs how skills are represented within the system. This comprehensive data model comprises various essential attributes, including:

Attributes	Description
ID	Unique identifier associated with a specific skill.
Name	Name of the Skill
Type	Type of the Skill (hard, soft, and language)

This comprehensive documentation is a valuable resource, providing detailed insights into the purpose and functionality of endpoints within the Skills API.

1. Skill Search

You can use the GET /skills endpoint to explore and find specific skills. This endpoint allows you to search by incorporating the following parameters within the request:

• searchTerm : This parameter enables you to filter skills based on a specific search term of your choice. It helps narrow down the results to match your desired criteria.

• limit: By including this parameter, you can specify the maximum number of skills you wish to retrieve. It allows you to control the number of skills returned to the search results.

• type: This parameter allows you to refine your search further by specifying the skills you want to retrieve. For instance, you can select from hard, soft, and language skills categories, tailoring the search to your specific requirements.

2. Skill Detection

If you need to identify skills from different types of textual content, such as CVs, job descriptions, or any other document type, you can use the POST /skills/detection endpoint. This robust endpoint provides the ability to detect skills by leveraging a range of parameters, including:

Skills Limit: By setting a skills limit parameter by type, you can control the maximum number of skills to be detected. This ensures that the skill detection process returns a manageable number of results that meet your requirements.

Document Type: The endpoint also enables you to customize the skill detection based on the type of document being analyzed. Whether it's a CV, job description, or any other type of textual content, considering the document type helps tailor the skill detection process to the specific context and needs of the document.

3. Skill Information

Our API provides multiple endpoints to facilitate access to skill-related information. You can utilize the GET /skills/{skillId} endpoint to obtain details about a specific skill. This endpoint will return essential information about the skill you specify.

If you require comprehensive details about a skill, including all its details and related skills, you can use the GET /skills/{skillId}/details endpoint. This endpoint provides a comprehensive overview of the skill, ensuring you have access to all the relevant information.

You can use the GET /skills/{skillId}/jobs endpoint to determine which jobs in your system require a specific skill. This endpoint allows you to retrieve a list of jobs that necessitate the particular skill you specify.

In cases where you require information about a group of skills rather than a single skill, you can employ the GET /skills/info endpoint. This endpoint enables you to retrieve comprehensive information about multiple skills simultaneously, streamlining the process of obtaining a holistic understanding of various skills.

You can utilize the POST /skills/related endpoint to find related skills to a particular skill. This endpoint facilitates the identification of skills that are closely associated with the skill you specify.

Users

The Users API provides a comprehensive set of functionalities for managing user information and data within the application.With this API, users can create, retrieve, update, delete, and filter user data to streamline user management processes. This documentation aims to provide developers with a detailed understanding of the User data model, its lifecycle, and the available endpoints for interacting with user information.

At the core of the Users API is the User data model, which serves as a structured representation of user information within the application. The User data model encompasses various attributes and fields that store essential information related to each user.

Here is an overview of the attributes included in our User data model:

Attributes	Description
ID	Unique identifier associated with a specific User.
externalId	To store the ID of a User from different system.
firstName	User first name.
lastName	User last name.
aboutMe	A brief description or biography of the user.
jobTitle	Current job title of the user.
department	Department where the user is employed.
location	Location of the user.
emailAddress	User email address.
phoneNumber	User contact phone number.
seniorityLevel	Seniority level of the user(0-6).
relocationPreference	User preference for relocation("not open". "open", "relocation only").
jobSeeking	Indicates if the user is currently seeking a job("not open", "open").
roles	Indicates the roles of the user

The Users use-case lifecycle encompasses multiple stages, starting from creation and extending to deletion and filtering. This comprehensive overview will outline the distinct stages that constitute the user lifecycle.

1. Create a User

The initial stage of the user lifecycle involves the creation of a new user. This can be accomplished by utilizing the POST /users endpoint, which allows for the creation of users by providing the necessary attributes from the user data model. While it is not obligatory to populate all attributes, there are a couple of mandatory fields that must be included when creating a user. These include firstName and lastName.

If there is limited information available about the user at the time of creation, users have the option to set some attributes as default values. This allows for the creation of a preliminary user profile, which can be further refined and supplemented with additional details later.

2. Retrieve a User

After a user has been successfully created, it becomes possible to retrieve the specific user by utilizing its userId. To retrieve a particular user, make use of the GET /users/{userId} endpoint. In the endpoint URL, substitute the placeholder {userId} with the actual user ID assigned during creation. This will allow you to access the detailed information and attributes associated with that specific user.

However, in the event that you do not have the user ID readily available, there is an alternative approach. By employing the GET /users endpoint, it is possible to retrieve a comprehensive list of all users present within the system. This endpoint provides an overview of all users, enabling you to browse through the available options and locate the desired user if the specific user ID is unknown.

3. Update a User

As users progress, it is often necessary to make updates to different fields associated with them. To facilitate these updates, the API offers the PATCH /users/{userId} endpoint, which allows for the modification of specific user attributes.

When utilizing the PATCH /users/{userId} endpoint, it is important to include the userId in the endpoint URL to specify the exact user that requires updating. Additionally, provide the updated fields within the request to reflect the desired changes. It is worth noting that all attributes are optional for updating, meaning that you can choose to modify one or more specific fields without the need to update every attribute.

4. Delete a User

Once a user's profile is no longer needed or should be removed, you have the option to delete it from the system. To achieve this, the API provides the DELETE /users/{userId} endpoint specifically designed for deleting users.

By utilizing the DELETE /users/{userId} endpoint, you can initiate the deletion process for a specific user. To indicate which user should be deleted, substitute the {userId} placeholder in the endpoint URL with the actual ID of the user you wish to remove.

Deleting a user through this endpoint permanently removes the user from the system, including all associated data and attributes. It is important to exercise caution when using this endpoint, as deleted users cannot be recovered. Therefore, it is recommended to ensure that the user truly needs to be deleted before invoking this endpoint.

5. User Filtering

The API offers a comprehensive user filtering feature, allowing you to refine your user search based on specific criteria. To explore the available filtering options, you can utilize the GET /users/filter endpoint, which provides a detailed list of fields that can be used to filter users. This endpoint returns a comprehensive set of filterable fields, enabling you to fine-tune your search based on desired attributes.

Once you have identified the relevant filter criteria, you can proceed to retrieve users that match those filters. The POST /users/filter endpoint serves this purpose, allowing you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of users that align with your specified criteria.

With the combination of the GET /users/filter and POST /users/filter endpoints, you can efficiently navigate and retrieve users that meet your specific requirements.

User Skills

This section provides a guide to managing user skills. It covers adding and updating hard and soft skills, retrieving hard and soft skills, adding language skills, and retrieving language skills. It emphasizes using specific endpoints for each task and the importance of effective skill management.

1. Add Hard-Soft skills to a user profile

After a user has been successfully created, you can add or update hard and soft skills for that user by utilizing their user ID. To manage skills for a particular user, use the POST /users/{userId}/hard-soft-skills endpoint. Substitute the placeholder {userId} in the endpoint URL with the assigned user ID. This endpoint allows you to add a new list of skills, overriding a user's existing skills. Along with the skillId, you can also specify the level to describe the user's proficiency in each skill.

2. Retrieve Hard-Soft skills from a user profile

The GET /users/{userId}/hard-soft-skills endpoint is your go-to for a comprehensive understanding of a user's hard and soft skills. This endpoint provides detailed information about the user's hard and soft skills, including the skill id, skill name, skill type, and proficiency level. This information lets you to deeply understand the user's competencies and strengths.

3. Add Language skills to a user profile

Adding language skills to a user profile is as simple as adding hard-soft skills. Like before, you can use the POST /users/{userId}/languages endpoint. This endpoint allows you to add a new list of language skills, overriding a user's existing skills. Just like hard-soft skills, you can specify the level to describe the user's proficiency in each language. The process is straightforward and familiar, making managing a user's language skills easy.

4. Retrieve Language skills from a user profile

You can utilize the GET /users/{userId}/languages endpoint to fetch comprehensive details about a particular user's language skills. This includes the skill ID, name, type, and proficiency level associated with each language skill.

Jobs

The Jobs API provides a comprehensive set of functionalities for users to effectively manage job postings within the application. With this API, users can create, retrieve, update, delete, and filter job postings to streamline their job management processes. This documentation aims to provide developers with a detailed understanding of the Job data model, its lifecycle, and the available endpoints for interacting with job postings.

At the core of the Jobs API is the Job data model, which serves as a structured representation of job postings within the application. The Job data model encompasses various attributes and fields that store essential information related to each job posting.

Here is an overview of the attributes included in our Job data model:

Attributes	Description
ID	Unique identifier associated with a specific job.
externalId	To store the ID of a job from a different system.
translations	Contains title and description for the job in various languages.
creator	User who created the job.
owner	User who is the primary contact for the job.
hiringManager	Assigned hiring manager for the job.
duration	Specifies whether the job is "permanent" or "fixed-term".
locations	An array of location IDs where the job is located.
workPlace	Indicates whether the job is "remote" or "on-site".
startDate	Start date of the job.
applicationUrl	URL of the job application.
state	Indicates the current state of the job (draft, published, hired, or archived).
seniorityLevel	Seniority level of the job.
skills	An array of skills (id and level) required for the job.
updatedAt	Time when the job was last updated.
publishedAt	Time when the job was published.

The Job lifecycle encompasses multiple stages, starting from creation and extending to deletion and filtering. This comprehensive overview will outline the distinct stages that constitute the job lifecycle.

1. Create a Job

The initial stage of the job lifecycle involves the creation of a new job. This can be accomplished by utilizing the POST /jobs endpoint, which allows for the creation of jobs by providing the necessary attributes from the job data model. While it is not obligatory to populate all attributes, there are several mandatory fields that must be included when creating a job. These include translations, location, workplace, state, and seniority level.

If there is limited information available about the job at the time of creation, users have the option to set the job's state to "Draft" using the state attribute. This allows for the creation of a preliminary job posting, which can be further refined and supplemented with additional details before transitioning to the "Published" state.

2. Retrieve a Job

After a job has been successfully created, it becomes possible to retrieve the specific job by utilizing its jobId. To retrieve a particular job, make use of the GET /jobs/{jobId} endpoint. In the endpoint URL, substitute the placeholder {jobId} with the actual job ID assigned during creation. This will allow you to access the detailed information and attributes associated with that specific job.

However, in the event that you do not have the job ID readily available, there is an alternative approach. By employing the GET /jobs endpoint, it is possible to retrieve a comprehensive list of all jobs present within the system. This endpoint provides an overview of all jobs, enabling you to browse through the available options and locate the desired job if the specific job ID is unknown.

3. Update a Job

As jobs evolve and progress, it is often necessary to make updates to different fields associated with them. To facilitate these updates, the API offers the PATCH /jobs/{jobId} endpoint, which allows for the modification of specific job attributes.

When utilizing the PATCH /jobs/{jobId} endpoint, it is important to include the jobId in the endpoint URL to specify the exact job that requires updating. Additionally, provide the updated fields within the request to reflect the desired changes. It is worth noting that all attributes are optional for updating, meaning that you can choose to modify one or more specific fields without the need to update every attribute.

However, there are certain attributes that cannot be set to null during the update process. These attributes include translations, locations, workPlace, state, seniority level, and skills. It is crucial to ensure that these attributes are provided with valid values and not left empty or null.

4. Delete a Job

Once the hiring process for a job is complete or when there is no longer a need for a job posting, you have the option to remove it from the system. To achieve this, the API provides the DELETE /jobs/{jobId} endpoint specifically designed for deleting jobs.

By utilizing the DELETE /jobs/{jobId} endpoint, you can initiate the deletion process for a specific job. To indicate which job should be deleted, substitute the {jobId} placeholder in the endpoint URL with the actual ID of the job you wish to remove.

Deleting a job through this endpoint permanently removes the job from the system, including all associated data and attributes. It is important to exercise caution when using this endpoint, as deleted jobs cannot be recovered. Therefore, it is recommended to ensure that the job truly needs to be deleted before invoking this endpoint.

5. Job filtering

The API offers a comprehensive job filtering feature, allowing you to refine your job search based on specific criteria. To explore the available filtering options, you can utilize the GET /jobs/filter endpoint, which provides a detailed list of fields that can be used to filter jobs. This endpoint returns a comprehensive set of filterable fields, enabling you to fine-tune your search based on desired attributes.

Once you have identified the relevant filter criteria, you can proceed to retrieve jobs that match those filters. The POST /jobs/filter endpoint serves this purpose, allowing you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of jobs that align with your specified criteria.

With the combination of the GET /jobs/filter and POST /jobs/filter endpoints, you can efficiently navigate and retrieve jobs that meet your specific requirements.

6. Job Description generation

In addition to its robust filtering capabilities, the Jobs API presents a seamless and highly efficient solution for generating comprehensive job descriptions using a job title. This feature is accomplished by harnessing the advanced capabilities of the OpenAI.

At the core of the Jobs API, the POST /jobs/generation endpoint serves as a remarkable tool for recruiters, empowering them to effortlessly create detailed job descriptions. Leveraging this endpoint, recruiters can input the job title and rely on the APIs sophisticated mechanisms to automatically generate comprehensive and accurate job descriptions.

7. Add users to Job Shortlist

The Shortlist feature allows recruiters to manage a list of candidates who have been shortlisted for a specific job. This feature helps in organizing and tracking potential candidates for a job role, making the recruitment process more efficient.

To get the current list of candidates who have been shortlisted for a specific job, use the GET /jobs/{jobId}/shortlist endpoint. This endpoint helps recruiters view the list of candidates who have been identified as potential fits for the job role, facilitating better tracking and management of the recruitment process.

8. Update users in Job Shortlist

To update the list of shortlisted candidates for a specific job, use the PATCH /jobs/{jobId}/shortlist endpoint. This endpoint provides flexibility in managing the shortlist by allowing recruiters to update the list of potential candidates dynamically, ensuring that the most suitable candidates are considered for the role.

9. Delete users from Job Shortlist

To delete one or more candidates from the shortlist for a specific job, use the DELETE /jobs/{jobId}/shortlist endpoint. This endpoint allows recruiters to clean up the shortlist by removing candidates who are no longer being considered for the job, ensuring that only relevant candidates remain in the list.

10. Add Notes to Shortlisted Candidate

To add notes to a specific candidate in the shortlist for a particular job, use the PATCH /jobs/{jobId}/shortlist endpoint with the candidateID query parameter. This endpoint helps recruiters keep detailed records of their observations and interactions with candidates, making it easier to review and decide on the suitability of each candidate during the recruitment process.

Job profiles

At the core of our job management system are the Job Profiles, the most detailed and specific component within an organization's job structure. Job Profiles precisely define the responsibilities, duties, required skills, and knowledge for particular positions. By providing detailed classifications, Job Profiles ensure clarity and consistency in role expectations, facilitating targeted recruitment, performance evaluation, and professional development within the organization. This documentation aims to provide developers with a comprehensive understanding of Job Profiles, their attributes, and the available endpoints for interacting with them.

Here is an overview of the attributes included in our Job profile data model:

Attributes	Description
ID	Unique identifier associated with a specific job profile.
externalId	To store the ID of a job profile from a different system.
translations	Contains title and description for the job profile in various languages.
creator	User who created the job profile.
owner	User who is the primary contact for the job profile.
state	Indicates the current state of the job profile (draft, active, or archived).
skills	An array of skills (id and level) required for the job profile.
updatedAt	Time when the job profile was last updated.

1. Create a Job Profile

To start the job profile lifecycle, you need to create a new job profile. You can do this by using the POST /job-profiles endpoint. This endpoint allows you to create job profiles by providing the required attributes from the job profile data model. While it's not mandatory to fill in all the attributes, you must include certain essential fields when creating a job profile, such as state and translations.

If you have limited information about the job profile when creating it, you can set the profile's state to "draft" using the state attribute. This will allow the creation of a preliminary job profile, which can be refined and updated with more details before changing its state to "Active."

2. Retrieve a Job Profile

Once you have successfully created a job profile, you can retrieve the specific profile by using its ID. Use the GET /job-profiles/{jobProfileId} endpoint to retrieve a particular job profile. In the endpoint URL, replace {jobProfileId} with the actual ID assigned during creation. This will allow you to access detailed information and attributes associated with that specific job profile, providing a comprehensive understanding of its characteristics.

If the profile ID is not readily available, there is an alternative approach. You can retrieve a comprehensive list of all job profiles present within the system by using the GET /job-profiles endpoint. This endpoint provides an overview of all profiles, allowing you to browse the options and locate the desired profile if the specific profile ID is unknown.

3. Update a Job Profile

As job profiles evolve and progress, the need to update different associated fields arises. The API offers the flexible PATCH /job-profiles/{jobProfileId} endpoint to empower you with control over these updates. This endpoint allows you to make specific modifications to job profile attributes, without the need to update every attribute. When utilizing the PATCH /job-profiles/{jobProfileId} endpoint, it is essential to include the profileId in the endpoint URL to specify the exact job profile that requires updating. Additionally, provide the updated fields within the request to reflect the desired changes. It is worth noting that all attributes are optional for updating, meaning that you can modify one or more specific fields without updating every attribute.

However, specific attributes cannot be null during the update process. These attributes include state and translations. It is crucial to ensure these attributes are met.

4. Delete a Job Profile

When a job profile is no longer needed or should be removed from the system, you can delete it using the API. The API provides the DELETE /job-profiles/{jobProfileId} endpoint, specifically designed for this purpose. This endpoint will delete the job profile and all associated data and attributes from the system. It's crucial to be cautious when using this endpoint, as deleted profiles cannot be recovered. Therefore, ensuring that the profile truly needs to be deleted before using this endpoint is essential.

5. Job Profile Filtering

The API offers a comprehensive job profile filtering feature, allowing you to refine your job profile search based on specific criteria. To explore the available filtering options, you can utilize the GET /job-profiles/filter endpoint, which provides a detailed list of fields that can be used to filter job profiles. This endpoint returns a comprehensive set of filterable fields, enabling you to fine-tune your search based on desired attributes.

Once you have identified the relevant filter criteria, you can retrieve job profiles matching those filters. The POST /job-profiles/filter endpoint allows you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of job profiles that align with your criteria.

With the combination of the GET /job-profiles/filter and POST /job-profiles/filter endpoints, you can efficiently navigate and retrieve job profiles that meet your specific requirements.

User recommendations

User Recommendations leverage user skills and job requirements to identify suitable job opportunities for users. This feature allows for a more targeted job search process by matching users to jobs based on their skill sets and recommending relevant job openings. This documentation aims to provide developers with a comprehensive understanding of User Recommendations and the available endpoints for interacting with them.

1. Job Recommendations for a User

To identify potential job opportunities that are a good fit for a user based on their skill sets, use the GET /users/{userId}/jobs endpoint. This functionality supports the job search process by providing a curated list of job openings, making it easier for users to find roles that match their qualifications and career aspirations.

2. Matching Skills and Score for a Job

To get detailed information on the matching skills, missing skills, and the overall matching score between the user and the job, use the GET /users/{userId}/jobs/{jobId}/matching endpoint. It helps in evaluating how well a user's skills align with the job requirements, identifying areas for improvement, and making informed decisions in the job application process.

Job recommendations

Job Recommendations leverage job and user skills to identify suitable job candidates. This feature allows for a more targeted recruitment process by matching users to jobs based on their skill sets and recommending upskilling where necessary. This documentation aims to provide developers with a comprehensive understanding of Job Recommendations and the available endpoints for interacting with them.

1. Candidate Recommendations for a Job

To identify potential candidates who are a good fit for the job based on their skill sets, use the GET /jobs/{jobId}/candidates endpoint. This functionality supports the recruitment process by providing a curated list of candidates, making it easier to find the right person for the role.

2. Single Candidate Information

To get detailed information about the specified candidate, such as their skills, experience, and any other relevant attributes, use the GET /jobs/{jobId}/candidates/{candidateId} endpoint. This detailed view helps recruiters and managers understand a candidate's qualifications and suitability for the job.

3. Learning Opportunities for Candidate Upskilling

To get a list of learning opportunities that can help a candidate address missing skills for a job, use the GET /jobs/{jobId}/candidates/{candidateId}/learning-opportunities endpoint. This endpoint identifies gaps in the candidate's skills and provides relevant learning opportunities to fill those gaps.

4. Matching Skills and Score for a Candidate

To get detailed information on the matching skills, missing skills, and the overall matching score between the candidate and the job, use the GET /jobs/{jobId}/candidates/{candidateId}/matching endpoint. It helps in evaluating how well a candidate's skills align with the job requirements, identifying areas for improvement, and making informed decisions in the recruitment process.

5. Filter Candidate Recommendations

The API also offers candidate filtering feature, allowing you to refine your recommended candidate list based on specific criteria. To explore the available filtering options, you can utilize the GET /jobs/{jobId}/candidates/filter endpoint, which provides a detailed list of fields that can be used to filter candidates.

Once you have identified the relevant filter criteria, you can proceed to retrieve candidates that match those filters. The POST /jobs/{jobId}/candidates/filter endpoint serves this purpose, allowing you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of candidates that align with your specified criteria.

The Upskilling section is designed to manage learning opportunities within the organization. It offers various functions for creating, retrieving, updating, deleting, filtering, and recommending learning opportunities. Additionally, users can be assigned learning opportunities to support their professional development.

Learning opportunities

Learning Opportunities form a crucial part of our job management system, providing a structured approach for employees to enhance their skills and knowledge. These opportunities can include courses, books and other educational activities. This documentation aims to provide developers with a comprehensive understanding of Learning Opportunities, their attributes, and the available endpoints for interacting with them.

Here is an overview of the attributes included in our Learning Opportunity data model:

Attributes	Description
ID	Unique identifier associated with a specific learning opportunity.
externalId	To store the ID of a learning opportunity from a different system.
translations	Contains title and description for the learning opportunity in various languages.
type	Indicates what type of learning opportunity (course).
ownerName	User who created the learning opportunity.
state	Indicates the current state of the learning opportunity (draft, published, or archived).
url	To store the url address of the learning opportunity
learningLanguage	To store in which language the learning opportunity is in.
provider	To store who is the provider of the learning opportunity.
skills	An array of skills at are associated with the learning opportunity.
createdAt	Time when the learning opportunity is created.
updatedAt	Time when the learning opportunity was last updated.

1. Create a Learning Opportunity

You need to create a new learning opportunity to initiate the learning opportunity lifecycle. You can do this by using the POST /learning-opportunities endpoint. This endpoint allows you to create learning opportunities by providing the required attributes from the learning opportunity data model. While filling in all the attributes is not mandatory, you must include specific essential fields when creating a learning opportunity, such as title, translations, state, and skills.

When creating the learning opportunity, you can set the profile's state to "draft" using the state attribute if you have limited information about it. This will allow a preliminary learning opportunity to be refined and updated with more details before changing its state to "Active."

2. Retrieve a Learning Opportunity

Once you have successfully created a learning opportunity, you can retrieve the specific opportunity by using its ID. Use the GET /learning-opportunities/{learningOpportunityId} endpoint to retrieve a particular learning opportunity. In the endpoint URL, replace {learningOpportunityId} with the ID assigned during creation. This will allow you to access detailed information and attributes associated with that specific learning opportunity, providing a comprehensive understanding of its characteristics.

If the opportunity ID is not readily available, there is an alternative approach. You can retrieve a comprehensive list of all learning opportunities present within the system by using the GET /learning-opportunities endpoint. This endpoint provides an overview of all opportunities, giving you the flexibility to browse the options and locate the desired opportunity if the specific opportunity ID is unknown.

3. Update a Learning Opportunity

As learning opportunities evolve and progress, the need to update different associated fields arises. The API offers the flexible PATCH /learning-opportunities/{learningOpportunityId} endpoint to empower you with control over these updates. This endpoint allows you to make specific modifications to learning opportunity attributes without the need to update every attribute. When utilizing this endpoint, it is essential to include the opportunityId in the endpoint URL to specify the exact learning opportunity that requires updating.

Additionally, provide the updated fields within the request to reflect the desired changes. It is worth noting that all attributes are optional for updating, meaning that you can modify one or more specific fields without updating every attribute. However, specific attributes cannot be null during the update process. These attributes include translations, type, state, and skills, and it is crucial to ensure they are met.

4. Delete a Learning Opportunity

When a learning opportunity is no longer needed or should be removed from the system, you can delete it using the API. The API provides the DELETE /learning-opportunities/{learningOpportunityId} endpoint, specifically designed for this purpose. This endpoint will delete the learning opportunity and all associated data and attributes from the system. It's crucial to be cautious when using this endpoint, as deleted opportunities cannot be recovered. Therefore, it is essential to delete the opportunity before using this endpoint.

5. Learning Opportunity Filtering

The API offers a comprehensive learning opportunity filtering feature, allowing you to refine your learning opportunity search based on specific criteria. To explore the available filtering options, you can utilize the GET /learning-opportunities/filter endpoint, which provides a detailed list of fields that can be used to filter learning opportunities. This endpoint returns a comprehensive set of filterable fields, enabling you to fine-tune your search based on desired attributes.

Once you have identified the relevant filter criteria, you can retrieve learning opportunities matching those filters. The POST /learning-opportunities/filter endpoint allows you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of learning opportunities that align with your criteria.

With the combination of the GET /learning-opportunities/filter and POST /learning-opportunities/filter endpoints, you can efficiently navigate and retrieve learning opportunities that meet your specific requirements.

6. Learning Opportunity Recommendations

Learning Opportunity Recommendations are designed to help users find relevant learning opportunities based on specific skills they wish to develop. This feature leverages the skillId to provide tailored recommendations, ensuring users can easily discover opportunities that align with their professional development goals.

To get personalized learning opportunity recommendations based on a specific skill, use the GET /learning-opportunities/recommendations endpoint. This endpoint requires the skillId as a query parameter to generate relevant recommendations.

Featured Opportunities

Featured Opportunities are specially highlighted learning opportunities assigned to specific users to promote their professional growth. These opportunities are curated based on the user’s role, skills, and career aspirations. This documentation aims to provide developers with a comprehensive understanding of Featured Opportunities, their attributes, and the available endpoints for interacting with them.

1. Set featured opportunity

To assign a learning opportunity to a user as a featured opportunity, you can do this by using the POST /featured-opportunities/{learningOpportunityId} endpoint. This endpoint allows you to assign learning opportunities to multiple users simultaneously.

2. Get users for featured opportunity

Once you assign a featured opportunity to users, you can retrieve the specific user's list using the learningOpportunityID. Use the GET /featured-opportunities/{learningOpportunityID} endpoint to get a particular user list. In the endpoint URL, replace {learningOpportunityID} with the ID assigned during creation. This will allow you to access detailed information which includes user ID, featured at what time, and who assigned it to the user.

3. Delete featured opportunity

When a featured opportunity is no longer needed or should be removed for a user, you can delete it using the DELETE /featured-opportunities/{learningOpportunity} endpoint. This endpoint will remove the featured opportunity and all associated data assigned to a user. It's crucial to be cautious when using this endpoint, as removed featured opportunities cannot be recovered. Therefore, ensuring that the user's opportunity is removed before using this endpoint is essential.

4. Get featured Opportunities for user

On the other hand, if a user wants to know which learning opportunities are assigned to them, they can utilize the GET /users/{userId}/featured-opportunities endpoint. By replacing the userId in the endpoint URL, this endpoint will provide a comprehensive list of all learning opportunities assigned to that particular user, including who assigned it to them and at what time.

The Job Architecture API gives you programmatic access to your organization's job structure. A job architecture organizes work into a five-level hierarchy, with each element carrying multilingual titles and descriptions:

Element	Description
Architecture	The top-level container, typically representing an organization or business unit.
Job Family	A broad grouping of related work, e.g. "Engineering".
Job Cluster	A subdivision of a family grouping closely related roles, e.g. "Software Development".
Job Role	A concrete role, e.g. "Backend Engineer", carrying a job profile with content and skills.
Job Level	A seniority variant of a role, e.g. "Senior Backend Engineer", with its own job profile.

1. Manage the Hierarchy

Use GET /job-architectures to list architectures and POST /job-architectures to create one. Each element type has standard read, create, update, and delete operations, for example GET /job-architectures/{jobArchitectureId}/families, POST /job-architectures/{jobArchitectureId}/families, and PATCH /job-architectures/{jobArchitectureId}/families/{jobFamilyId}. Clusters follow the same pattern below families, and roles and levels are managed via /job-architectures/{jobArchitectureId}/roles/{jobRoleId} and /job-architectures/{jobArchitectureId}/levels/{jobLevelId}.

For integrations that synchronize a job architecture from an external system of record (for example SAP SuccessFactors Talent Intelligence Hub), families and clusters can be created with pre-defined identifiers using PUT /job-architectures/{jobArchitectureId}/families/{jobFamilyId} and PUT /job-architectures/{jobArchitectureId}/families/{jobFamilyId}/clusters/{jobClusterId}, which makes the synchronization idempotent.

2. Job Profiles

Every role and level carries a job profile: structured content sections plus the skills detected in that content. Use GET /job-profiles to list profiles, GET /job-profiles/{jobProfileId} to read one, and PATCH /job-profiles/{jobProfileId} to update content. After editing content you can re-run skill detection with POST /job-profiles/{jobProfileId}/detect-skills.

3. Search and Filtering

GET /job-architectures/{jobArchitectureId}/search finds elements matching a text pattern within one architecture. For structured queries, POST /job-architectures/filter filters items across all architectures and POST /job-architectures/{jobArchitectureId}/filter within one; the corresponding GET .../filter endpoints list the available filter fields and values.

4. Versioning, Review, and Comments

Roles and levels are versioned: GET .../roles/{jobRoleId}/versions lists the history and GET .../roles/{jobRoleId}/versions/{version} returns a specific version (levels analogously). A review workflow lets you assign a reviewer to a job profile (POST /job-profiles/{jobProfileId}/reviewer, with search, update, and removal endpoints alongside) and discuss changes through comments on architecture items via /job-architectures/{jobArchitectureId}/items/{itemId}/comments, including replies and thread resolution.

5. Archiving

Instead of deleting, roles and levels can be archived and unarchived — individually (POST .../roles/{jobRoleId}/archive) or in bulk (POST .../roles/archive). Archived elements are hidden from active views but remain recoverable, which makes archiving the safe default for lifecycle management.

6. Bulk Generation

POST /job-architectures/{jobArchitectureId}/generate generates job architecture entities in batch for an architecture, controlled by the type query parameter. Generation runs asynchronously when deferred: the endpoint responds with 202 Accepted if the task was scheduled and 200 OK if it executed immediately.

7. Career Tracks

Career tracks group levels across roles into progression paths. Manage them with the CRUD endpoints under /job-architectures/{jobArchitectureId}/career-tracks.

8. Job Profile Templates

The job profile template controls the structure of generated job profiles in an architecture. Read the current template with GET /job-architecture/{jsaId}/job-profile-templates, and set or remove it with PUT and DELETE on /job-architecture/{jsaId}/job-profile-templates/{templateId}.

In addition to the REST API, Cobrainer exposes the Job Architecture to AI agents through the Model Context Protocol (MCP). MCP lets tools like Claude Code, Codex, Cursor, and Microsoft Copilot read and edit your job architecture conversationally, with the same tenant isolation and permission checks as the REST API.

Servers

Cobrainer provides four MCP servers, scoped by capability. Each is a stateless HTTP endpoint on the API host:

Server	Endpoint	Required permission
Knowledge Base (read)	https://api.be.cobrainer.cloud/mcp/knowledge-base-read	CAN_READ_KNOWLEDGE_BASE
Job Architecture read	https://api.be.cobrainer.cloud/mcp/ja-read	CAN_READ_JOB_ARCHITECTURE
Architect (write)	https://api.be.cobrainer.cloud/mcp/ja-architect	CAN_EDIT_JOB_ARCHITECTURE
Reviewer (write)	https://api.be.cobrainer.cloud/mcp/ja-reviewer	CAN_REVIEW_JOB_PROFILES

The complete, always-current tool catalog for every server — including each tool's input and output schema — is published on the MCP dashboard. A machine-friendly index of this whole documentation site is available at llms.txt.

Authentication

MCP requests authenticate with an API key sent in the X-API-KEY header, exactly like REST API requests. The key must belong to a user or service with the permission required by the server you connect to (see table above). Contact our support team to obtain an API key with the appropriate permissions.

Client Setup

Replace <YOUR_API_KEY> and pick the server endpoint matching what the agent should be allowed to do. The examples use the read server; write access works the same way with the architect or reviewer endpoint.

Claude Code

claude mcp add --transport http cobrainer-ja https://api.be.cobrainer.cloud/mcp/ja-read \
  --header "X-API-KEY: <YOUR_API_KEY>"

Codex

Add to ~/.codex/config.toml:

[mcp_servers.cobrainer-ja]
url = "https://api.be.cobrainer.cloud/mcp/ja-read"
http_headers = { "X-API-KEY" = "<YOUR_API_KEY>" }

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "cobrainer-ja": {
      "url": "https://api.be.cobrainer.cloud/mcp/ja-read",
      "headers": { "X-API-KEY": "<YOUR_API_KEY>" }
    }
  }
}

Microsoft Copilot (VS Code)

Add to .vscode/mcp.json:

{
  "servers": {
    "cobrainer-ja": {
      "type": "http",
      "url": "https://api.be.cobrainer.cloud/mcp/ja-read",
      "headers": { "X-API-KEY": "<YOUR_API_KEY>" }
    }
  }
}

Microsoft 365 Copilot (Teams, Edge, microsoft365.com)

Use this guide to make Cobrainer capabilities available through a Microsoft 365 Copilot agent in Microsoft Teams, Microsoft Edge, and the Microsoft 365 Copilot web app.

Guide verified: 25 August 2026

Audience: Microsoft Copilot Studio makers and administrators

Microsoft updates Copilot Studio regularly. Labels and screen layouts may change after the verification date above.

How it works

Microsoft 365 Copilot surfaces access Cobrainer through an agent configured in Microsoft Copilot Studio. The agent is connected to the Cobrainer MCP server and published through the following channels:

• Microsoft Teams uses the Microsoft Teams publication channel.
• Microsoft Edge and microsoft365.com use the Microsoft 365 Copilot publication channel.

Prerequisites

Before starting, make sure you have:

• Access to Microsoft Copilot Studio.
• Permission to create, publish, and share an agent in the selected Power Platform environment.
• Copilot Credits allocated to that environment, or pay-as-you-go billing enabled. Without credits, Copilot Studio cannot preview or run the agent.
• A Cobrainer API key belonging to a user or service account with the scope required by the selected MCP server.
• Permission to publish to Microsoft 365 Copilot and Microsoft Teams, or an administrator who can approve the agent.

Security: Use a dedicated, least-privileged API key. Never place the key in agent instructions, documentation, prompts, screenshots, source control, or chat messages.

1. Choose a Cobrainer MCP server and create an API key

Choose the server that matches the capabilities the agent should have:

Capability	MCP server URL	API key scope
Read from the Knowledge Base	https://api.be.cobrainer.cloud/mcp/knowledge-base-read	Viewer
Read Job Architecture data	https://api.be.cobrainer.cloud/mcp/ja-read	Viewer
Edit Job Architecture data	https://api.be.cobrainer.cloud/mcp/ja-architect	Job Architect
Review Job Architecture data	https://api.be.cobrainer.cloud/mcp/ja-reviewer	Reviewer

Create an API key with the scope required by the selected server:

1. Sign in to Cobrainer.
2. Open your personal preferences and select API keys.
3. Select Create new API key.
4. Give the key a recognizable name that describes its intended use.
5. Select Viewer, Reviewer, or Job Architect, as shown in the table above.
6. Set an appropriate expiration date.
7. Create the key and copy it immediately.
8. Store it in an approved password manager or secrets-management system.

The MCP server authenticates with an API key in the following HTTP header:

X-API-KEY: <YOUR_API_KEY>

2. Create an agent in Microsoft Copilot Studio

1. Open Microsoft Copilot Studio.
2. Select the correct organizational environment in the environment selector.
3. On the Home page, select Agent.
4. Give the agent a clear name, for example Cobrainer Assistant.
5. Add a description explaining which Cobrainer capabilities the agent provides.
6. Add instructions that tell the agent when and how to use Cobrainer.

Example instructions:

You are a Cobrainer assistant.

Use the available Cobrainer tools to help users with the capabilities provided
by the configured MCP server.

Always retrieve current information from Cobrainer before answering questions
about organizational data. Clearly state when requested information cannot be found.

Operate only within the actions exposed by the configured Cobrainer tools. Never
claim that an action succeeded unless the tool confirms it.

Keep responses concise and factual. Ask a clarifying question when the requested
Cobrainer data or requested action is ambiguous.

If the agent should answer only from Cobrainer, remove Search all websites from the Knowledge section.

3. Add the Cobrainer MCP server

1. Open the agent's Build tab.
2. In the right-side components panel, select the + beside Tools.
3. In Add a tool, select Add beside the search field.
4. Select Model Context Protocol (MCP).
5. Enter the following values. The server name, description, and URL should match the MCP server chosen in step 1:

Field	Value
Server name	A short name describing the selected Cobrainer capability
Server description	A clear description of what the server lets the agent do and when it should be used
Server URL	The MCP server URL selected in step 1
Authentication	API key
Parameter type	Header
Header name	X-API-KEY
Key value	Your Cobrainer API key

6. Select Add.

4. Create and select the connection

Copilot Studio creates a Power Platform connector and then asks which connection the agent should use.

1. In Select a connection, open the dropdown beside Not connected.
2. Choose the option to create a connection.
3. Optionally enter a display name that identifies the selected Cobrainer server.
4. Paste the Cobrainer API key into the X-API-KEY field.
5. Select Create and wait for processing to finish.
6. Select the newly created connection.
7. Select Add in the underlying dialog.
8. Confirm that the Cobrainer server appears under Tools on the Build tab.

5. Test before publishing

1. Select Preview.

2. Start a new chat.

3. Ask a question that requires one of the selected server's capabilities. For the Job Architecture read server, for example:

   What job roles are available in our organization?
   

4. Confirm that the response contains correct and current Cobrainer data.

6. Publish the agent

1. Return to Build.
2. Confirm the agent name, description, instructions, Cobrainer tool, and selected connection.
3. Select the chevron beside Publish in the upper-right corner.
4. In the publication dialog, configure these channels:
   • Microsoft 365 Copilot
   • Microsoft Teams
5. Review the agent details.
6. Select Publish and wait for publication to complete.
7. Share the agent with the intended users or groups, or submit it to the organization catalog for administrator approval.

Changes made after publication are not visible to users until you publish again.

The API has comprehensive error handling to provide clear and informative responses when issues occur. This section provides details for the error handling approach and explains how error responses are structured.

All endpoints in the API have error responses that provide detailed information about encountered issues. These responses are designed to help developers understand and resolve problems effectively. Error responses include the following elements:

HTTP Status Codes

Error responses are accompanied by appropriate HTTP status codes to indicate the nature of the error. Some of the status codes for error responses are:

• 400 Bad Request: The request is invalid or malformed.
• 401 Unauthorized: The request requires user authentication.
• 403 Forbidden: The authenticated user does not have permission to access the requested resource.
• 404 Not Found: The requested resource was not found.
• 500 Internal Server Error: An unexpected error occurred on the server.

Error Message Structure

Error responses contain a structured message that provides information about the issue. The message typically includes the following elements:

• error code: A code that can be used for programmatic error handling.
• message: A human-readable description of the error, providing additional context, such as validation errors or specific error details

For more details about the specific error responses for each endpoint, please refer to the API Reference section. The API Reference provides comprehensive documentation for each endpoint, including the possible error scenarios, associated status codes, and detailed error messages.

To ensure fair usage and prevent abuse, rate limiting mechanisms have been implemented on the application endpoints. The following information outlines the specific rate limits that are enforced and describes how they are applied.

Rate Limiting Rules

The application endpoints adhere to the following rate limits:

• Each user ID is allowed to send a maximum of 500 requests per minute.

• Once the limit of 500 requests per minute is reached, the user ID will be restricted to 50 requests per 10 minutes.

These rate limits serve to maintain a balanced and equitable usage of the API, preventing any individual user from overwhelming the system with excessive requests. By carefully controlling the rate at which requests are accepted, the API ensures a smooth and reliable experience for all users.

This section is dedicated to helping you resolve any issues or challenges you may encounter while working with the Talent API. Our support team is committed to providing timely assistance and ensuring a smooth experience throughout your integration process.

If you require support or have any questions regarding the Talent API, there are several ways to seek assistance:

• Documentation: First and foremost, make sure to thoroughly review the API documentation. It contains comprehensive information about the APIs features, endpoints, request/response structures, and common use cases. Frequently, the documentation will answer many of your questions and provide guidance on proper API usage.

• Report an incident: Email support@cobrainer.com. Please include any relevant error messages, request/response examples, and steps to reproduce the problem.

• Report a vulnerability: Email security@cobrainer.com.

• Data privacy requests: Email privacy@cobrainer.com.

• Service status: Visit our public status page.

The API Reference section serves as a comprehensive guide, offering detailed information about the various endpoints available within the Talent API. Within this section, you will find distinct sections dedicated to jobs, skills, users, learning opportunities, and the job architecture, each providing an exhaustive list of endpoints specific to that area.

For every endpoint, the API reference provides in-depth details about the request and response structures, including any mandatory parameters that need to be supplied and the expected data formats for successful interaction with the API.

Operations to manage reviewers of job profiles

Operations to work with users

Automation assessment KPIs derived from work task assessments

Operations to work with job postings