{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/timely/main/json-schema/timely-v1-hour-schema.json",
  "title": "V1.Hour",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/timely-openapi.json#/components/schemas/V1.Hour",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Unique identifier for the time entry"
    },
    "uid": {
      "type": "string",
      "description": "Unique string identifier for the time entry"
    },
    "user": {
      "type": "object",
      "description": "User who logged this time",
      "properties": {
        "id": {
          "type": "integer",
          "exclusiveMinimum": 0
        },
        "email": {
          "type": "string",
          "minLength": 1
        },
        "name": {
          "type": "string",
          "minLength": 1
        },
        "avatar": {
          "type": "object",
          "properties": {
            "large_retina": {
              "format": "uri",
              "type": "string"
            },
            "large": {
              "format": "uri",
              "type": "string"
            },
            "medium_retina": {
              "format": "uri",
              "type": "string"
            },
            "medium": {
              "format": "uri",
              "type": "string"
            },
            "small_retina": {
              "format": "uri",
              "type": "string"
            },
            "small": {
              "format": "uri",
              "type": "string"
            },
            "timeline": {
              "format": "uri",
              "type": "string"
            }
          },
          "required": [
            "large_retina",
            "large",
            "medium_retina",
            "medium"
          ]
        },
        "active": {
          "type": "boolean"
        },
        "day_view_onboarded": {
          "type": "boolean"
        },
        "memory_onboarded": {
          "type": "boolean"
        },
        "created_at": {
          "type": [
            "null",
            "string"
          ],
          "format": "date-time"
        },
        "updated_at": {
          "type": [
            "null",
            "string"
          ],
          "format": "date-time"
        },
        "last_received_memories_date": {
          "type": [
            "null",
            "string"
          ],
          "format": "date-time"
        },
        "sign_in_count": {
          "type": [
            "null",
            "integer"
          ]
        },
        "external_id": {
          "type": [
            "null",
            "string"
          ]
        },
        "time_zone": {
          "type": [
            "null",
            "string"
          ]
        },
        "memory_retention_days": {
          "type": [
            "null",
            "integer"
          ]
        },
        "type": {
          "type": [
            "null",
            "string"
          ]
        }
      },
      "required": [
        "id",
        "email",
        "name",
        "avatar"
      ]
    },
    "project": {
      "type": "object",
      "description": "Project this time was logged to",
      "properties": {
        "id": {
          "type": "integer"
        },
        "can_edit_details": {
          "type": "boolean"
        },
        "active": {
          "type": "boolean"
        },
        "account_id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "null",
            "string"
          ]
        },
        "color": {
          "type": "string"
        },
        "rate_type": {
          "type": "string"
        },
        "billable": {
          "type": "boolean"
        },
        "created_at": {
          "type": "integer"
        },
        "updated_at": {
          "type": "integer"
        },
        "external_id": {
          "type": [
            "null",
            "string"
          ]
        },
        "budget_scope": {
          "type": [
            "null",
            "string"
          ]
        },
        "client": {
          "type": "object",
          "properties": {
            "id": {
              "type": "integer"
            },
            "name": {
              "type": "string"
            },
            "color": {
              "type": "string"
            },
            "active": {
              "type": "boolean"
            },
            "external_id": {
              "type": [
                "null",
                "string"
              ]
            },
            "updated_at": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "id",
            "name",
            "color",
            "active",
            "updated_at"
          ]
        },
        "required_notes": {
          "type": "boolean"
        },
        "required_labels": {
          "type": "boolean"
        },
        "budget_expired_on": {
          "type": [
            "null",
            "string"
          ]
        },
        "has_recurrence": {
          "type": "boolean"
        },
        "enable_labels": {
          "type": "string"
        },
        "default_labels": {
          "type": "boolean"
        },
        "allow_only_one_tag": {
          "type": "boolean"
        },
        "currency": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "iso_code": {
              "type": "string"
            },
            "symbol": {
              "type": "string"
            },
            "symbol_first": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "name",
            "iso_code",
            "symbol",
            "symbol_first"
          ]
        },
        "team_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "budget": {
          "type": [
            "null",
            "integer"
          ]
        },
        "budget_type": {
          "type": [
            "null",
            "string"
          ]
        },
        "budget_calculation": {
          "type": [
            "null",
            "string"
          ]
        },
        "hour_rate": {
          "type": [
            "null",
            "number"
          ]
        },
        "hour_rate_in_cents": {
          "type": [
            "null",
            "number"
          ]
        },
        "budget_progress": {
          "type": [
            "null",
            "number"
          ]
        },
        "budget_percent": {
          "type": [
            "null",
            "number"
          ]
        },
        "invoice_by_budget": {
          "type": [
            "null",
            "boolean"
          ]
        },
        "labels": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "sequence": {
                "type": "integer"
              },
              "parent_id": {
                "type": [
                  "null",
                  "integer"
                ]
              },
              "emoji": {
                "type": [
                  "null",
                  "string"
                ]
              },
              "active": {
                "type": "boolean"
              },
              "external_id": {
                "type": [
                  "null",
                  "string"
                ]
              },
              "created_at": {
                "type": [
                  "null",
                  "string"
                ],
                "format": "date-time"
              },
              "updated_at": {
                "type": [
                  "null",
                  "string"
                ],
                "format": "date-time"
              },
              "tic": {
                "type": "object",
                "properties": {
                  "uri": {
                    "type": "string"
                  },
                  "tool_id": {
                    "type": [
                      "null",
                      "string"
                    ]
                  },
                  "external_url": {
                    "type": [
                      "null",
                      "string"
                    ]
                  }
                },
                "required": [
                  "uri"
                ]
              },
              "children": {
                "type": "array"
              }
            },
            "required": [
              "id",
              "name",
              "sequence",
              "active"
            ]
          }
        },
        "label_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "required_label_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "default_label_ids": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "created_from": {
          "type": "string"
        },
        "cost": {
          "type": "object",
          "properties": {
            "fractional": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "amount": {
              "type": "number"
            },
            "currency_code": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "estimated_cost": {
          "type": "object",
          "properties": {
            "fractional": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "amount": {
              "type": "number"
            },
            "currency_code": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "billed_cost": {
          "type": "object",
          "properties": {
            "fractional": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "amount": {
              "type": "number"
            },
            "currency_code": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "unbilled_cost": {
          "type": "object",
          "properties": {
            "fractional": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "amount": {
              "type": "number"
            },
            "currency_code": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "duration": {
          "type": "object",
          "properties": {
            "hours": {
              "type": "integer"
            },
            "minutes": {
              "type": "integer"
            },
            "seconds": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "total_hours": {
              "type": "number"
            },
            "total_seconds": {
              "type": "integer"
            },
            "total_minutes": {
              "type": "integer"
            }
          }
        },
        "estimated_duration": {
          "type": "object",
          "properties": {
            "hours": {
              "type": "integer"
            },
            "minutes": {
              "type": "integer"
            },
            "seconds": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "total_hours": {
              "type": "number"
            },
            "total_seconds": {
              "type": "integer"
            },
            "total_minutes": {
              "type": "integer"
            }
          }
        },
        "billed_duration": {
          "type": "object",
          "properties": {
            "hours": {
              "type": "integer"
            },
            "minutes": {
              "type": "integer"
            },
            "seconds": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "total_hours": {
              "type": "number"
            },
            "total_seconds": {
              "type": "integer"
            },
            "total_minutes": {
              "type": "integer"
            }
          }
        },
        "unbilled_duration": {
          "type": "object",
          "properties": {
            "hours": {
              "type": "integer"
            },
            "minutes": {
              "type": "integer"
            },
            "seconds": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "total_hours": {
              "type": "number"
            },
            "total_seconds": {
              "type": "integer"
            },
            "total_minutes": {
              "type": "integer"
            }
          }
        }
      },
      "required": [
        "id",
        "active",
        "account_id",
        "name",
        "description",
        "color",
        "rate_type",
        "billable",
        "created_at",
        "updated_at",
        "client",
        "required_notes",
        "required_labels",
        "has_recurrence",
        "enable_labels",
        "default_labels",
        "allow_only_one_tag",
        "currency",
        "team_ids",
        "labels",
        "label_ids",
        "required_label_ids",
        "default_label_ids",
        "created_from"
      ]
    },
    "duration": {
      "type": "object",
      "description": "Actual time spent (use this for reported hours)",
      "properties": {
        "hours": {
          "type": "integer"
        },
        "minutes": {
          "type": "integer"
        },
        "seconds": {
          "type": "integer"
        },
        "formatted": {
          "type": "string",
          "minLength": 1
        },
        "total_hours": {
          "type": "number"
        },
        "total_seconds": {
          "type": "integer"
        },
        "total_minutes": {
          "type": "integer"
        }
      },
      "required": [
        "hours",
        "minutes",
        "seconds",
        "formatted",
        "total_hours",
        "total_seconds",
        "total_minutes"
      ]
    },
    "estimated_duration": {
      "type": "object",
      "description": "Planned or estimated time",
      "properties": {
        "hours": {
          "type": "integer"
        },
        "minutes": {
          "type": "integer"
        },
        "seconds": {
          "type": "integer"
        },
        "formatted": {
          "type": "string",
          "minLength": 1
        },
        "total_hours": {
          "type": "number"
        },
        "total_seconds": {
          "type": "integer"
        },
        "total_minutes": {
          "type": "integer"
        }
      },
      "required": [
        "hours",
        "minutes",
        "seconds",
        "formatted",
        "total_hours",
        "total_seconds",
        "total_minutes"
      ]
    },
    "cost": {
      "type": "object",
      "description": "Actual cost of this time entry",
      "properties": {
        "fractional": {
          "type": "integer"
        },
        "formatted": {
          "type": "string",
          "minLength": 1
        },
        "amount": {
          "type": "number"
        },
        "currency_code": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "fractional",
        "formatted",
        "amount",
        "currency_code"
      ]
    },
    "estimated_cost": {
      "type": "object",
      "description": "Estimated cost based on planned time",
      "properties": {
        "fractional": {
          "type": "integer"
        },
        "formatted": {
          "type": "string",
          "minLength": 1
        },
        "amount": {
          "type": "number"
        },
        "currency_code": {
          "type": "string",
          "minLength": 1
        }
      },
      "required": [
        "fractional",
        "formatted",
        "amount",
        "currency_code"
      ]
    },
    "day": {
      "type": "string",
      "description": "Date this time was logged (YYYY-MM-DD format)"
    },
    "note": {
      "type": [
        "null",
        "string"
      ],
      "description": "Description or notes about the work performed"
    },
    "sequence": {
      "type": "integer",
      "description": "Order of this entry within the day"
    },
    "estimated": {
      "type": "boolean",
      "description": "True for planned/scheduled time, false for actual logged time"
    },
    "timer_state": {
      "type": "string",
      "description": "Timer status: running, stopped, or paused"
    },
    "timer_started_on": {
      "type": "integer",
      "description": "Unix timestamp when timer started (0 if not running)"
    },
    "timer_stopped_on": {
      "type": "integer",
      "description": "Unix timestamp when timer stopped (0 if never stopped)"
    },
    "label_ids": {
      "type": "array",
      "description": "Tags/categories applied to this entry",
      "items": {
        "type": "integer"
      }
    },
    "user_ids": {
      "type": "array",
      "description": "Users associated with this entry (for team entries)",
      "items": {
        "type": "integer"
      }
    },
    "updated_at": {
      "type": "integer",
      "description": "Unix timestamp of last modification"
    },
    "created_at": {
      "type": "integer",
      "description": "Unix timestamp when entry was created"
    },
    "created_from": {
      "type": "string",
      "description": "Source that created this entry (web, mobile, api, etc.)"
    },
    "updated_from": {
      "type": "string",
      "description": "Source of last update (web, mobile, api, etc.)"
    },
    "billed": {
      "type": "boolean",
      "description": "True if this time has been invoiced to the client"
    },
    "billable": {
      "type": "boolean",
      "description": "True if this time can be billed to the client"
    },
    "to": {
      "type": [
        "null",
        "string"
      ],
      "description": "End time in HH:MM format (24-hour)"
    },
    "from": {
      "type": [
        "null",
        "string"
      ],
      "description": "Start time in HH:MM format (24-hour)"
    },
    "deleted": {
      "type": "boolean",
      "description": "True if this entry has been deleted (soft delete)"
    },
    "hour_rate": {
      "type": "number",
      "description": "Billing rate per hour for this entry"
    },
    "hour_rate_in_cents": {
      "type": "integer",
      "description": "Billing rate in cents (for precise calculations)"
    },
    "creator_id": {
      "type": [
        "null",
        "integer"
      ],
      "description": "User who created this entry"
    },
    "updater_id": {
      "type": [
        "null",
        "integer"
      ],
      "description": "User who last modified this entry"
    },
    "external_id": {
      "type": [
        "null",
        "string"
      ],
      "description": "Your system's identifier for integration mapping"
    },
    "entry_ids": {
      "type": "array",
      "description": "Memory timeline entries that make up this logged time",
      "items": {
        "type": "integer"
      }
    },
    "suggestion_id": {
      "type": [
        "null",
        "integer"
      ],
      "description": "AI suggestion that generated this entry"
    },
    "autosheet_proposal_id": {
      "type": [
        "null",
        "string"
      ],
      "description": "AutoSheet proposal UUID this hour was created from"
    },
    "draft": {
      "type": "boolean",
      "description": "True if this is a draft (not yet submitted)"
    },
    "manage": {
      "type": "boolean",
      "description": "True if current user can edit/delete this entry"
    },
    "forecast_id": {
      "type": [
        "null",
        "integer"
      ],
      "description": "Task that this entry fulfills"
    },
    "billed_at": {
      "type": [
        "null",
        "string"
      ],
      "description": "ISO 8601 timestamp when this was invoiced"
    },
    "external_link_ids": {
      "type": "array",
      "description": "Links to related resources (tickets, docs, etc.)",
      "items": {
        "type": "integer"
      }
    },
    "internal_cost": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "fractional": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "amount": {
              "type": "number"
            },
            "currency_code": {
              "type": "string",
              "minLength": 1
            }
          },
          "required": [
            "fractional",
            "formatted",
            "amount",
            "currency_code"
          ]
        },
        {
          "type": "object",
          "properties": {}
        }
      ],
      "description": "Your internal cost for this work (for profit tracking)"
    },
    "estimated_internal_cost": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "fractional": {
              "type": "integer"
            },
            "formatted": {
              "type": "string",
              "minLength": 1
            },
            "amount": {
              "type": "number"
            },
            "currency_code": {
              "type": "string",
              "minLength": 1
            }
          },
          "required": [
            "fractional",
            "formatted",
            "amount",
            "currency_code"
          ]
        },
        {
          "type": "object",
          "properties": {}
        }
      ],
      "description": "Estimated internal cost"
    },
    "internal_cost_rate": {
      "type": "integer",
      "description": "Internal cost rate in cents per hour"
    },
    "profit": {
      "type": "integer",
      "description": "Profit margin in cents (billable cost - internal cost)"
    },
    "profitability": {
      "type": "integer",
      "description": "Profit percentage ((profit / cost) * 100)"
    },
    "locked_reason": {
      "type": [
        "null",
        "string"
      ],
      "description": "Why this entry is locked (e.g., \"Approved timesheet\")"
    },
    "locked": {
      "type": "boolean",
      "description": "True if entry is locked and cannot be edited"
    },
    "invoice_id": {
      "type": [
        "null",
        "integer"
      ],
      "description": "Invoice this entry appears on (if billed)"
    },
    "timestamps": {
      "type": "array",
      "description": "Individual time segments that make up this entry",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "hour_id": {
            "type": "integer"
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "entry_ids": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        },
        "required": [
          "id",
          "hour_id",
          "from",
          "to",
          "entry_ids"
        ]
      }
    },
    "state": {
      "type": [
        "object",
        "null"
      ],
      "allOf": [
        {
          "$ref": "#/$defs/V1.State"
        }
      ],
      "description": "Workflow state (for approval processes)",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "icon": {
          "type": [
            "null",
            "string"
          ]
        },
        "color": {
          "type": "string"
        },
        "billed": {
          "type": "boolean"
        },
        "locked": {
          "type": "boolean"
        },
        "system_managed": {
          "type": "boolean"
        },
        "custom": {
          "type": "boolean"
        },
        "deleted": {
          "type": "boolean"
        },
        "updated_at": {
          "type": "integer"
        },
        "created_at": {
          "type": "integer"
        },
        "permissions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "role_id": {
                "type": "integer"
              },
              "state_id": {
                "type": "integer"
              },
              "team_lead": {
                "type": "boolean"
              },
              "project_lead": {
                "type": "boolean"
              },
              "operation": {
                "type": "string"
              },
              "updated_at": {
                "type": "integer"
              },
              "created_at": {
                "type": "integer"
              }
            },
            "required": [
              "id",
              "role_id",
              "state_id",
              "team_lead",
              "project_lead",
              "operation",
              "updated_at",
              "created_at"
            ]
          }
        }
      },
      "required": [
        "id",
        "name",
        "color",
        "billed",
        "locked",
        "system_managed",
        "custom",
        "deleted",
        "updated_at",
        "created_at",
        "permissions"
      ]
    },
    "external_links": {
      "type": "array",
      "description": "Attached links to tickets, PRs, documents, etc.",
      "items": {
        "type": "object",
        "properties": {
          "provider_type": {
            "type": "string"
          },
          "provider_id": {
            "type": "string"
          },
          "external_id": {
            "type": "string"
          },
          "uri": {
            "type": [
              "null",
              "string"
            ]
          },
          "linked_work_item_id": {
            "type": [
              "null",
              "integer"
            ]
          },
          "data": {
            "type": "object"
          }
        },
        "required": [
          "provider_type",
          "provider_id",
          "external_id"
        ]
      }
    },
    "linked_work_items": {
      "type": [
        "array",
        "null"
      ],
      "description": "Linked work items from external tools. Present when include_linked_metadata=true and integrations feature is enabled.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "null",
              "string"
            ]
          },
          "title": {
            "type": [
              "null",
              "string"
            ]
          },
          "sync_status": {
            "type": [
              "null",
              "string"
            ]
          }
        }
      }
    }
  },
  "required": [
    "id",
    "uid",
    "user",
    "project",
    "duration",
    "estimated_duration",
    "cost",
    "estimated_cost",
    "day",
    "sequence",
    "estimated",
    "timer_state",
    "timer_started_on",
    "timer_stopped_on",
    "label_ids",
    "user_ids",
    "updated_at",
    "created_at",
    "created_from",
    "updated_from",
    "billed",
    "billable",
    "deleted",
    "hour_rate",
    "hour_rate_in_cents",
    "entry_ids",
    "draft",
    "manage",
    "external_link_ids",
    "internal_cost_rate",
    "profit",
    "profitability",
    "locked",
    "timestamps",
    "external_links"
  ],
  "$defs": {
    "V1.State": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "icon": {
          "type": [
            "null",
            "string"
          ]
        },
        "color": {
          "type": "string"
        },
        "billed": {
          "type": "boolean"
        },
        "locked": {
          "type": "boolean"
        },
        "system_managed": {
          "type": "boolean"
        },
        "custom": {
          "type": "boolean"
        },
        "deleted": {
          "type": "boolean"
        },
        "updated_at": {
          "type": "integer"
        },
        "created_at": {
          "type": "integer"
        },
        "permissions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "role_id": {
                "type": "integer"
              },
              "state_id": {
                "type": "integer"
              },
              "team_lead": {
                "type": "boolean"
              },
              "project_lead": {
                "type": "boolean"
              },
              "operation": {
                "type": "string"
              },
              "updated_at": {
                "type": "integer"
              },
              "created_at": {
                "type": "integer"
              }
            },
            "required": [
              "id",
              "role_id",
              "state_id",
              "team_lead",
              "project_lead",
              "operation",
              "updated_at",
              "created_at"
            ]
          }
        }
      },
      "required": [
        "id",
        "name",
        "color",
        "billed",
        "locked",
        "system_managed",
        "custom",
        "deleted",
        "updated_at",
        "created_at",
        "permissions"
      ]
    }
  }
}