# /api/v3/time_entries/{id}
---
delete:
  summary: Delete time entry
  tags:
    - Time entries
  description: Permanently deletes the specified time entry.
  operationId: delete_time_entry
  parameters:
    - name: id
      description: Time entry id
      example: 1
      in: path
      required: true
      schema:
        type: integer
  responses:
    '204':
      description: Returned if the time entry was deleted successfully.
    '403':
      description: Returned if the client does not have sufficient permissions
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
            message: You are not authorized to access this resource.
    '404':
      description: |-
        Returned if the time entry does not exist or if the user does not have sufficient permissions to see the time entry.

        **Required permission** `view time entries` in the project the time entry is assigned to or `view own time entries` for time entries belonging to the user
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
            message: The requested resource could not be found.
    '406':
      $ref: '../components/responses/missing_content_type.yml'
    '415':
      $ref: '../components/responses/unsupported_media_type.yml'

get:
  summary: Get time entry
  tags:
    - Time entries
  description: Retrieves a single time entry identified by the given id.
  operationId: get_time_entry
  parameters:
    - name: id
      description: time entry id
      example: 1
      in: path
      required: true
      schema:
        type: integer
  responses:
    '200':
      description: OK
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/time_entry_model.yml'
    '404':
      description: |-
        Returned if the time entry does not exist or if the user does not have permission to view them.

        **Required permission**
        - `view time entries` in the project the time entry is assigned to or
        - `view own time entries` for time entries belonging to the user
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
            message: The requested resource could not be found.

patch:
  summary: update time entry
  tags:
    - Time Entries
  description: |-
    Updates the given time entry by 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: update_time_entry
  parameters:
    - name: id
      description: Time entry id
      example: 1
      in: path
      required: true
      schema:
        type: integer
  responses:
    '200':
      description: OK
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/time_entry_model.yml'
    '400':
      $ref: '../components/responses/invalid_request_body.yml'
    '403':
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** Edit (own) time entries, depending on what time entry is being modified.
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
            message: You are not authorized to access this resource.
      headers: { }
    '406':
      $ref: '../components/responses/missing_content_type.yml'
    '415':
      $ref: '../components/responses/unsupported_media_type.yml'
    '422':
      description: |-
        Returned if:

        * a constraint for a property was violated (`PropertyConstraintViolation`)
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _embedded:
              details:
                attribute: workPackage
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
            message: Work package is invalid.
