Runn

Runn Users API

The Users API from Runn — 5 operation(s) for users.

GitHub OpenAPI

Operations 7

GET /users/ List users #
GET /users/{userId} Show a user #
PATCH /users/{userId} Update a user #
DELETE /users/{userId} Delete a user #
GET /users/{userId}/views/ List allocated views for a user #
POST /users/{userId}/views/{viewId} Allocate a view to a user #
DELETE /users/{userId}/views/{viewId}/ Remove allocated view from user #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/runn/openapi/runn-users-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/runn/json-schema/runn-person-schema.json
📊
JSONSchema
https://artifacts.apis.io/runn/json-schema/runn-project-schema.json
📊
JSONSchema
https://artifacts.apis.io/runn/json-schema/runn-invitation-schema.json
📊
JSONSchema
https://artifacts.apis.io/runn/json-schema/runn-reports-hours-people-schema.json
📊
JSONSchema
https://artifacts.apis.io/runn/json-schema/runn-reports-hours-projects-schema.json
📊
JSONSchema
https://artifacts.apis.io/runn/json-schema/runn-actual-time-entry-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/runn:runn-users-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

runn-users-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Runn Users API
  version: 1.0.0
  description: 'See the full documentation and guide to using the Runn API.


    The domain for your API endpoint can be found in Accounts > Settings > API in your Runn application'
servers:
- url: https://api.runn.io
  description: EU Server
- url: https://api.us.runn.io
  description: US Server
security:
- bearerAuth: []
tags:
- name: Users
paths:
  /users/:
    get:
      operationId: listUsers
      summary: List users
      description: See `POST /invitations` for creating users
      parameters:
      - schema:
          type: string
        in: query
        name: cursor
        required: false
        description: Cursor for paginated requests
      - schema:
          default: 50
          minimum: 1
          maximum: 200
          type: integer
        in: query
        name: limit
        required: false
        description: The number of results per page
      - schema:
          $ref: '#/components/schemas/ModifiedAfter'
        in: query
        name: modifiedAfter
        required: false
      - schema:
          default: 1.0.0
          enum:
          - 1.0.0
        in: header
        name: accept-version
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  values:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  nextCursor:
                    type: string
                    nullable: true
                required:
                - values
                - nextCursor
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
      tags:
      - Users
  /users/{userId}:
    get:
      operationId: getUser
      summary: Show a user
      parameters:
      - schema:
          type: integer
        in: path
        name: userId
        required: true
      - schema:
          default: 1.0.0
          enum:
          - 1.0.0
        in: header
        name: accept-version
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      tags:
      - Users
    patch:
      operationId: updateUser
      summary: Update a user
      description: Currently supports updating people team access for restricted people managers.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                peopleTeams:
                  maxItems: 1000
                  uniqueItems: true
                  description: Teams whose members this restricted people manager can manage. An empty array revokes every team grant; omitting the field leaves them untouched. Sending this field, including an empty array, returns 403 when the account does not have the feature.
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        minimum: 1
                        maximum: 2147483647
                        type: integer
                    required:
                    - id
      parameters:
      - schema:
          type: integer
        in: path
        name: userId
        required: true
      - schema:
          default: 1.0.0
          enum:
          - 1.0.0
        in: header
        name: accept-version
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      tags:
      - Users
    delete:
      operationId: deleteUser
      summary: Delete a user
      parameters:
      - schema:
          type: integer
        in: path
        name: userId
        required: true
      - schema:
          default: 1.0.0
          enum:
          - 1.0.0
        in: header
        name: accept-version
        required: true
      responses:
        '204':
          description: Default Response
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      tags:
      - Users
  /users/{userId}/views/:
    get:
      operationId: listUserViews
      summary: List allocated views for a user
      parameters:
      - schema:
          type: string
        in: query
        name: cursor
        required: false
        description: Cursor for paginated requests
      - schema:
          default: 50
          minimum: 1
          maximum: 200
          type: integer
        in: query
        name: limit
        required: false
        description: The number of results per page
      - schema:
          type: integer
        in: path
        name: userId
        required: true
      - schema:
          default: 1.0.0
          enum:
          - 1.0.0
        in: header
        name: accept-version
        required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  values:
                    type: array
                    items:
                      $ref: '#/components/schemas/View'
                  nextCursor:
                    type: string
                    nullable: true
                required:
                - values
                - nextCursor
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      tags:
      - Users
  /users/{userId}/views/{viewId}:
    post:
      operationId: createUserView
      summary: Allocate a view to a user
      parameters:
      - schema:
          type: integer
        in: path
        name: userId
        required: true
        description: The Id of the user to allocate the view to.
      - schema:
          type: integer
        in: path
        name: viewId
        required: true
        description: The Id of the view to allocate to the user.
      - schema:
          default: 1.0.0
          enum:
          - 1.0.0
        in: header
        name: accept-version
        required: true
      responses:
        '201':
          description: Default Response
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '409':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
      tags:
      - Users
  /users/{userId}/views/{viewId}/:
    delete:
      operationId: deleteUserView
      summary: Remove allocated view from user
      parameters:
      - schema:
          type: integer
        in: path
        name: userId
        required: true
      - schema:
          type: integer
        in: path
        name: viewId
        required: true
      - schema:
          default: 1.0.0
          enum:
          - 1.0.0
        in: header
        name: accept-version
        required: true
      responses:
        '204':
          description: Default Response
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      tags:
      - Users
components:
  schemas:
    NotFound:
      type: object
      properties:
        error:
          type: string
          enum:
          - Not Found
        message:
          type: string
        statusCode:
          type: number
          enum:
          - 404
      required:
      - error
      - message
      - statusCode
    Conflict:
      type: object
      properties:
        error:
          type: string
          enum:
          - Conflict
        message:
          type: string
        statusCode:
          type: number
          enum:
          - 409
      required:
      - error
      - message
      - statusCode
    User:
      type: object
      properties:
        id:
          type: integer
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        email:
          type: string
        personId:
          type: integer
          nullable: true
        permissions:
          type: object
          properties:
            type:
              type: string
              enum:
              - superuser
              - admin
              - editor
              - viewer_all
              - viewer_basic
              - timesheet_only
              deprecated: true
              description: 'Mapped permission type (deprecated: use userType)'
            userType:
              type: string
              enum:
              - superuser
              - admin
              - manager
              - contributor
              description: The user's unmapped database permission type
            financial:
              type: string
              enum:
              - all
              - no_salaries
              - restricted
              - none
            editProjects:
              type: string
              enum:
              - all
              - specific
              - restricted
              - none
              deprecated: true
              description: 'Edit projects permission (deprecated: use manageProjects)'
            manageProjects:
              type: string
              enum:
              - all
              - specific
              - restricted
              - none
            editOthers:
              type: string
              enum:
              - all
              - none
              deprecated: true
              description: 'Edit others permission (deprecated: use managePeople)'
            managePeople:
              type: string
              enum:
              - all
              - restricted
              - none
            manageAccount:
              type: boolean
            addAllPeopleToProjects:
              type: boolean
            viewPlanner:
              type: boolean
          required:
          - type
          - userType
          - financial
          - editProjects
          - manageProjects
          - editOthers
          - managePeople
          - manageAccount
          - addAllPeopleToProjects
          - viewPlanner
        peopleTeams:
          description: Teams this user manages people through when their managePeople permission is 'restricted'. Always returned; empty when they have no team grants.
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
            required:
            - id
        createdAt:
          type: string
          format: date-time
          description: Timestamp of when the object was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of when the object was last updated.
      required:
      - id
      - firstName
      - lastName
      - email
      - personId
      - permissions
      - peopleTeams
      - createdAt
      - updatedAt
    View:
      type: object
      properties:
        id:
          minimum: 0
          type: integer
        name:
          type: string
        description:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: Timestamp of when the object was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of when the object was last updated.
      required:
      - id
      - name
      - description
      - createdAt
      - updatedAt
    Unauthorized:
      type: object
      properties:
        error:
          type: string
          enum:
          - Unauthorized
        message:
          type: string
          enum:
          - Unauthorized
        statusCode:
          type: number
          enum:
          - 401
      required:
      - error
      - message
      - statusCode
    BadRequest:
      type: object
      properties:
        error:
          type: string
          enum:
          - Bad Request
        message:
          type: string
        statusCode:
          type: number
          enum:
          - 400
      required:
      - error
      - message
      - statusCode
    ModifiedAfter:
      description: 'If provided, will only return objects modified after this timestamp. Format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ.'
      anyOf:
      - format: date
        type: string
      - format: date-time
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-readme:
  proxy-enabled: false