Invite enterprise members¶

POST /api/v8/enterprises/{enterprise}/memberships/{username}

Call this endpoint to invite enterprise members.

Supported access tokens¶

AtomGit user access tokens

Anonymous access allowed¶

This endpoint does not allow anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`enterprise`	path	integer	Yes	Enterprise ID
`username`	path	string	Yes	Username (username/login)
`access_token`	query	string	Yes	User authorization code

Request Body:

The request body specifies the permission and role of the invited member, submitted as application/json. The body may be omitted, in which case the new member gets push permission by default.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "permission": {
      "description": "Member permission: participant (pull), developer (push), maintainer (admin), customized (custom role); defaults to `push`",
      "type": "string",
      "enum": ["pull", "push", "admin", "customized"],
      "default": "push"
    },
    "role_id": {
      "description": "Role ID; required when `permission` is `customized`",
      "type": "string"
    }
  }
}

Response parameters¶

Field	Type	Always returned	Nullable	Description
`followers_url`	string	Yes	No	URL of the followers list
`html_url`	string	Yes	No	URL of the profile page
`id`	string	Yes	No	Member ID
`login`	string	Yes	No	Username (username/login)
`name`	string	Yes	No	Name
`type`	string	Yes	No	User type
`url`	string	Yes	No	URL of the user's profile page
`permissions`	object	Yes	No	Member permission information

permissions object

Field	Type	Always returned	Nullable	Description
`permissions.admin`	boolean	Yes	No	Whether the member has administrator permission
`permissions.customized`	boolean	Yes	No	Whether the member has custom role permission
`permissions.push`	boolean	Yes	No	Whether the member has push permission
`permissions.pull`	boolean	Yes	No	Whether the member has pull permission

Error response¶

The endpoint returns the following error structures when parameter validation fails, the caller is unauthenticated, or the resource does not exist (error field names follow what the backend actually returns).

400 Invalid parameters

{
  "error": "invalid_request",
  "message": "Parameter username cannot be empty"
}

401 Unauthenticated

{
  "error": "unauthorized",
  "message": "Missing or invalid access token"
}

404 Resource does not exist

{
  "error": "not_found",
  "message": "Enterprise or member does not exist"
}

HTTP status codes¶

Status code	Description
`200`	Success (OK)
`400`	Invalid parameters (Bad Request)
`401`	Authentication required (Requires authentication)
`404`	Resource does not exist (Not Found)

Request example¶

Parameter notes¶

Replace <enterprise> with the enterprise ID (an integer), <username> with the username (username/login) of the invited member, and <token> with your AtomGit user access token.

cURL¶

curl -X POST 'https://api.atomgit.com/api/v8/enterprises/<enterprise>/memberships/<username>?access_token=<token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"permission": "push"}'

JavaScript¶

// Native fetch (Node.js 18+ / browsers)
const response = await fetch(
  "https://api.atomgit.com/api/v8/enterprises/<enterprise>/memberships/<username>?access_token=<token>",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: JSON.stringify({ permission: "push" }),
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.post(
    "https://api.atomgit.com/api/v8/enterprises/<enterprise>/memberships/<username>",
    params={"access_token": "<token>"},
    headers={
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={"permission": "push"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "followers_url": "https://api.atomgit.com/api/v5/users/xiaogang2/followers",
  "html_url": "https://api.atomgit.com/xiaogang2",
  "id": "65ffca965079ba0d1c00f6f2",
  "login": "xiaogang2",
  "name": "Xiao Gang 2",
  "type": "User",
  "url": "https://api.atomgit.com/api/v5/xiaogang2",
  "permissions": {
    "admin": false,
    "customized": true,
    "push": true,
    "pull": true
  }
}

Error codes¶

Error code	Description
`400`	Invalid parameters or the request cannot be parsed
`401`	Unauthenticated or invalid credentials (missing or invalid access credentials)
`404`	Request path or resource does not exist
`405`	Request method not supported
`429`	Too many requests; rate limit triggered
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc