corteza/api/system/spec/user.json

{
  "Title": "Users",
  "Interface": "User",
  "Struct": [
    {
      "imports": [
        "github.com/cortezaproject/corteza-server/system/types"
      ]
    }
  ],
  "Parameters": null,
  "Protocol": "",
  "Authentication": [
    "Client ID",
    "Session ID"
  ],
  "Path": "/users",
  "APIs": [
    {
      "Name": "list",
      "Method": "GET",
      "Title": "Search users (Directory)",
      "Path": "/",
      "Parameters": {
        "get": [
          {
            "name": "userID",
            "required": false,
            "title": "Filter by user ID",
            "type": "[]string"
          },
          {
            "name": "roleID",
            "required": false,
            "title": "Filter by role membership",
            "type": "[]string"
          },
          {
            "name": "query",
            "required": false,
            "title": "Search query to match against users",
            "type": "string"
          },
          {
            "name": "username",
            "required": false,
            "title": "Search username to match against users",
            "type": "string"
          },
          {
            "name": "email",
            "required": false,
            "title": "Search email to match against users",
            "type": "string"
          },
          {
            "name": "handle",
            "required": false,
            "title": "Search handle to match against users",
            "type": "string"
          },
          {
            "name": "kind",
            "required": false,
            "title": "Kind (normal, bot)",
            "type": "types.UserKind"
          },
          {
            "name": "incDeleted",
            "required": false,
            "title": "[Deprecated] Include deleted users (requires 'access' permission)",
            "type": "bool"
          },
          {
            "name": "incSuspended",
            "required": false,
            "title": "[Deprecated] Include suspended users",
            "type": "bool"
          },
          {
            "name": "deleted",
            "required": false,
            "title": "Exclude (0, default), include (1) or return only (2) deleted users",
            "type": "uint"
          },
          {
            "name": "suspended",
            "required": false,
            "title": "Exclude (0, default), include (1) or return only (2) suspended users",
            "type": "uint"
          },
          {
            "name": "limit",
            "title": "Limit",
            "type": "uint"
          },
          {
            "name": "offset",
            "title": "Offset",
            "type": "uint"
          },
          {
            "name": "page",
            "title": "Page number (1-based)",
            "type": "uint"
          },
          {
            "name": "perPage",
            "title": "Returned items per page (default 50)",
            "type": "uint"
          },
          {
            "name": "sort",
            "title": "Sort items",
            "type": "string"
          }
        ]
      }
    },
    {
      "Name": "create",
      "Method": "POST",
      "Title": "Create user",
      "Path": "/",
      "Parameters": {
        "post": [
          {
            "name": "email",
            "required": true,
            "title": "Email",
            "type": "string"
          },
          {
            "name": "name",
            "required": false,
            "title": "Name",
            "type": "string"
          },
          {
            "name": "handle",
            "required": false,
            "title": "Handle",
            "type": "string"
          },
          {
            "name": "kind",
            "required": false,
            "title": "Kind (normal, bot)",
            "type": "types.UserKind"
          }
        ]
      }
    },
    {
      "Name": "update",
      "Method": "PUT",
      "Title": "Update user details",
      "Path": "/{userID}",
      "Parameters": {
        "path": [
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ],
        "post": [
          {
            "name": "email",
            "required": true,
            "title": "Email",
            "type": "string"
          },
          {
            "name": "name",
            "required": true,
            "title": "Name",
            "type": "string"
          },
          {
            "name": "handle",
            "required": false,
            "title": "Handle",
            "type": "string"
          },
          {
            "name": "kind",
            "required": false,
            "title": "Kind (normal, bot)",
            "type": "types.UserKind"
          }
        ]
      }
    },
    {
      "Name": "read",
      "Method": "GET",
      "Title": "Read user details",
      "Path": "/{userID}",
      "Parameters": {
        "path": [
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ]
      }
    },
    {
      "Name": "delete",
      "Method": "DELETE",
      "Title": "Remove user",
      "Path": "/{userID}",
      "Parameters": {
        "path": [
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ]
      }
    },
    {
      "Name": "suspend",
      "Method": "POST",
      "Title": "Suspend user",
      "Path": "/{userID}/suspend",
      "Parameters": {
        "path": [
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ]
      }
    },
    {
      "Name": "unsuspend",
      "Method": "POST",
      "Title": "Unsuspend user",
      "Path": "/{userID}/unsuspend",
      "Parameters": {
        "path": [
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ]
      }
    },
    {
      "Name": "undelete",
      "Method": "POST",
      "Title": "Undelete user",
      "Path": "/{userID}/undelete",
      "Parameters": {
        "path": [
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ]
      }
    },
    {
      "Name": "setPassword",
      "Method": "POST",
      "Title": "Set's or changes user's password",
      "Path": "/{userID}/password",
      "Parameters": {
        "path": [
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ],
        "post": [
          {
            "name": "password",
            "required": true,
            "sensitive": true,
            "title": "New password",
            "type": "string"
          }
        ]
      }
    },
    {
      "Name": "membershipList",
      "Method": "GET",
      "Title": "Add member to a role",
      "Path": "/{userID}/membership",
      "Parameters": {
        "path": [
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ]
      }
    },
    {
      "Name": "membershipAdd",
      "Method": "POST",
      "Title": "Add role to a user",
      "Path": "/{userID}/membership/{roleID}",
      "Parameters": {
        "path": [
          {
            "name": "roleID",
            "required": true,
            "title": "Role ID",
            "type": "uint64"
          },
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ]
      }
    },
    {
      "Name": "membershipRemove",
      "Method": "DELETE",
      "Title": "Remove role from a user",
      "Path": "/{userID}/membership/{roleID}",
      "Parameters": {
        "path": [
          {
            "name": "roleID",
            "required": true,
            "title": "Role ID",
            "type": "uint64"
          },
          {
            "name": "userID",
            "required": true,
            "title": "User ID",
            "type": "uint64"
          }
        ]
      }
    },
    {
      "Name": "triggerScript",
      "Method": "POST",
      "Title": "Fire system:user trigger",
      "Path": "/{userID}/trigger",
      "Parameters": {
        "path": [
          {
            "name": "userID",
            "required": true,
            "title": "ID",
            "type": "uint64"
          }
        ],
        "post": [
          {
            "name": "script",
            "required": true,
            "title": "Script to execute",
            "type": "string"
          }
        ]
      }
    }
  ]
}