Introduction:

Usually, setting up a project is done via the CircleCI UI. However, you might have a use-case that requires or benefits from automating the setup process.

You can programmatically set up a CircleCI project by leveraging the Create a Project API v2 endpoint.

Prerequisites:

If you don't already have one that you can use, you'll need to generate a personal API token for a user who has, at least, write access on the related project.

The project must have a main branch containing a config.yml file in the .circleci directory.

Please note that this endpoint is experimental. There is an older but less powerful v1 endpoint which will be covered at the end of this article if you are not comfortable using the v2 endpoint.

Instructions:

1. Retrieve the personal API token
2. Programmatically set up the project
   • The following example uses cURL+shell but you can wrap the API call and use it with your favourite language.
     

     curl --request POST \
     --url https://circleci.com/api/v2/project/<VCS>/<ORG>/<PROJECT> \
     --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Outcome:

If the operation is successful, you'll receive a 201 response.

Using the v1 API

If you are unable to or uncomfortable using the v2 endpoint, you can make use of the "Follow a New Project on CircleCI" API v1 endpoint.

Instructions:

1. Retrieve the personal API token
2. Programmatically set up the project
   • The following example uses cURL+shell but you can wrap the API call and use it with your favourite language.
     

     curl --location --request POST 'https://circleci.com/api/v1.1/project/<VCS>/<ORG_NAME>/<NEW_REPO_NAME>/follow' \
     
     --header 'Content-Type: application/json' \
     
     -u '<API_TOKEN>:' \
     
     --data-raw '{
     
     "first_build": "true"
     
     }'

Outcome:

If the operation is successful, you'll receive a 200 response.

Additional Resources:

• CircleCI API Developer's Guide
• Managing API Tokens
• CircleCI API Reference