# /api/v3/time_entries
---
get:
  parameters:
  - description: Page number inside the requested collection.
    example: '25'
    in: query
    name: offset
    required: false
    schema:
      default: 1
      type: integer
  - description: Number of elements to display per page.
    example: '25'
    in: query
    name: pageSize
    required: false
    schema:
      type: integer
  - description: |-
      JSON specifying sort criteria.
      Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported sorts are:

      + id: Sort by primary key

      + hours: Sort by logged hours

      + spent_on: Sort by spent on date

      + created_at: Sort by time entry creation datetime

      + updated_at: Sort by the time the time entry was updated last
    example: '[["spent_on", "asc"]]'
    in: query
    name: sortBy
    required: false
    schema:
      default: '["spent_on", "asc"]'
      type: string
  - description: |-
      JSON specifying filter conditions.
      Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint. Currently supported filters are:

      + work_package: Filter time entries by work package

      + project: Filter time entries by project

      + user: Filter time entries by users

      + spent_on: Filter time entries by spent on date

      + created_at: Filter time entries by creation datetime

      + updated_at: Filter time entries by the last time they where updated

      + activity: Filter time entries by time entry activity
    example: '[{ "work_package": { "operator": "=", "values": ["1", "2"] } }, { "project":
      { "operator": "=", "values": ["1"] } }]'
    in: query
    name: filters
    required: false
    schema:
      type: string
  responses:
    '200':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _embedded:
                  elements:
                  - _links:
                      activity:
                        href: "/api/v3/time_entries/activities/18"
                        title: Some time entry activity
                      delete:
                        href: "/api/v3/time_entries/1"
                        method: delete
                      project:
                        href: "/api/v3/projects/1"
                        title: Some project
                      self:
                        href: "/api/v3/time_entries/1"
                      updateImmediately:
                        href: "/api/v3/time_entries/1"
                        method: patch
                      user:
                        href: "/api/v3/users/2"
                        title: Some user
                      workPackage:
                        href: "/api/v3/work_packages/1"
                        title: Some work package
                    _type: TimeEntry
                    comment:
                      format: plain
                      html: "<p>Some comment</p>"
                      raw: Some comment
                    createdAt: '2015-03-20T12:56:56Z'
                    hours: PT5H
                    id: 5
                    spentOn: '2015-03-20'
                    updatedAt: '2015-03-20T12:56:56Z'
                  - _links:
                      activity:
                        href: "/api/v3/time_entries/activities/14"
                        title: some other time entry activity
                      project:
                        href: "/api/v3/projects/42"
                        title: Some other project
                      self:
                        href: "/api/v3/time_entries/2"
                      user:
                        href: "/api/v3/users/6"
                        title: Some other project
                      workPackage:
                        href: "/api/v3/work_packages/541"
                        title: Some other work package
                    _type: TimeEntry
                    comment:
                      format: plain
                      html: "<p>Another comment</p>"
                      raw: Another comment
                    createdAt: '2015-03-20T12:56:56Z'
                    hours: PT7H
                    id: 10
                    spentOn: '2015-03-21'
                    updatedAt: '2015-03-20T12:56:56Z'
                _links:
                  changeSize:
                    href: "/api/v3/time_entries?offset=1&pageSize=%7Bsize%7D"
                    templated: true
                  createTimeEntry:
                    href: "/api/v3/time_entries/form"
                    method: post
                  createTimeEntryImmediately:
                    href: "/api/v3/time_entries"
                    method: post
                  jumpTo:
                    href: "/api/v3/time_entries?offset=%7Boffset%7D&pageSize=2"
                    templated: true
                  nextByOffset:
                    href: "/api/v3/time_entries?offset=2&pageSize=2"
                  self:
                    href: "/api/v3/time_entries?offset=1&pageSize=2"
                _type: Collection
                count: 2
                offset: 1
                pageSize: 2
                total: 39
          schema:
            "$ref": "../components/schemas/list_time_entries_model.yml"
      description: OK
      headers: {}
    '400':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
                message:
                - Filters Invalid filter does not exist.
      description: Returned if the client sends invalid request parameters e.g. filters
      headers: {}
    '403':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to view this resource.
      description: Returned if the client is not logged in and login is required.
      headers: {}
  tags:
  - Time Entries
  description: Lists time entries. The time entries returned depend on the filters
    provided and also on the permission of the requesting user.
  operationId: List_time_entries
  summary: List time entries
post:
  responses:
    '201':
      content:
        application/hal+json:
          schema:
            "$ref": "../components/schemas/view_time_entry_model.yml"
      description: Created
      headers: {}
    '400':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request body was not a single JSON object.
      description: Occurs when the client did not send a valid JSON object in the
        request body.
      headers: {}
    '403':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** Log time
      headers: {}
    '422':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _embedded:
                  details:
                    attribute: workPackage
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Work package is invalid.
      description: |-
        Returned if:

        * a constraint for a property was violated (`PropertyConstraintViolation`)
      headers: {}
  tags:
  - Time Entries
  description: Creates a new time entry applying the attributes provided in the body.
    Please note that while there is a fixed set of attributes, custom fields can extend
    a time entries' attributes and are accepted by the endpoint.
  operationId: Create_Time_entry
  summary: Create Time entry