Create a new project in a group using API

I’m kind of new to the GitLab experience and I’m wanting to automate the local repo creation process with a Linux command line command that will create a project in GitLab using the API. I found the documentation hard to understand. I would like to use curl to do the API project creation. Can anyone give me an example of the HTTPS call (preferably using curl but any help is appreciated) that creates a new specified project in a existing specified group?

You can try this:

curl --header "PRIVATE-TOKEN: gDGnJwv56z2Xfj2B83Es" -X POST ""

where private token can be found in your profile/account. You can add more options as stated in

for example:

curl --header "PRIVATE-TOKEN: gDGnJwv56z2Xfj2B83Es" -X POST ""

PS. I’m in the process of rewriting the docs and the API will have many more examples with curl and other tools.


@axil thanks that helps alot! Lots of examples in the docs would definitely help.

@axil I have successfully created projects using my token. Cool.

But when I tried adding a namespace_id=pyt to my curl command like:

curl --header "PRIVATE-TOKEN: <my token>" -X POST ""

I get a response of:

{"message":{"namespace":["is not valid"],"limit_reached":[]}}

I could not find anything about a limit in either my profile or group settings. What is limiting this?

Also I could not get the ‘description’ option to work either.

The message seems a little cryptic, but the is not valid answer explains it.

namespace_id is the id of the namespace, where namespace your username or an organization you can create repos to. When you first create a repo you are presented with a json object like so:

   "archived" : false,
   "merge_requests_enabled" : true,
   "path" : "foobartest3",
   "default_branch" : null,
   "namespace" : {
      "owner_id" : 3585,
      "updated_at" : "2013-03-21T05:40:35.000Z",
      "membership_lock" : false,
      "path" : "axil",
      "id" : 3467,
      "created_at" : "2013-03-21T05:40:35.000Z",
      "avatar" : null,
      "description" : "",
      "name" : "axil"
   "wiki_enabled" : true,
   "ssh_url_to_repo" : "",
   "tag_list" : [],
   "http_url_to_repo" : "",
   "path_with_namespace" : "axil/foobartest3",
   "id" : 416441,
   "created_at" : "2015-08-19T22:10:41.503Z",
   "name_with_namespace" : "Achilleas Pipinellis / foobartest3",
   "description" : null,
   "name" : "foobartest3",
   "web_url" : "",
   "public" : false,
   "snippets_enabled" : false,
   "avatar_url" : null,
   "forks_count" : 0,
   "creator_id" : 3585,
   "owner" : {
      "username" : "axil",
      "avatar_url" : "",
      "name" : "Achilleas Pipinellis",
      "web_url" : "",
      "id" : 3585,
      "state" : "active"
   "issues_enabled" : true,
   "visibility_level" : 0,
   "star_count" : 0,
   "last_activity_at" : "2015-08-19T22:10:41.503Z"

watch that its namespace_id is 3467. So that’s the number you are looking for. For a list of namespaces you are part of, run:

curl --header "PRIVATE-TOKEN: <token>" ""

As for the description, I guess you used spaces right? Make sure to replace them with %20 or + like:

curl --header "PRIVATE-TOKEN: token" -X POST ""

See for more info.

Tip: If you have perl installed you can pipe the output of the curl commands to | json_pp and the information will be more human readable :smile:


@axil That did it! Thanks! I went looking for an “ID” for namespace in gitlab but I didn’t find it. The show me all the id for all the groups I’m part of. So I add that and it worked. You also got the space thing right. Didn’t even think of that. Very cool everything thing is working!


You can receive same respond

{“message”:{“namespace”:[“is not valid”],“limit_reached”:}}

when you have bad permissions which is really confusing.

User have to have permission at least “Maintainer” on group.

Hi ,
I wanted to create the project on below project location (group/subgroup).

But always the project is getting created on default location of group.

Kindly please do the needful.



1 Like

@santhuhappy24 I also have the same question

Thanks everyone for asking this question.

There is no subgroup API. Subgroups are groups with Parent_id specified. So to create a Subgroup you use the Group API and specify the Parent_id which is the integer id of the group. The group api group/ will return the first id with that matching name.

@dsumenkovic the question was " Create a new project in a group using API"

So there is no answer about the existence of this endpoint. Would you give some news?

@LuanComputacao … it is answered, basically, with Create a new project in a group using API

The only bit of additional information you’ll need (available reading the documentation) is adding the namespace_id parameter, which is identified in the response marked as “Solution” here: Create a new project in a group using API

V3 is deprecated, any update to V4?

curl -H "Content-Type:application/json" -d "{ \"name\": \"newRepo\", \"namespace_id\": \"ID\" }"
@AronWaterAron @LuanComputacao