# Convert a timestamp between formats and time zones

`POST /v1/convert/timestamp/{from_format}/to/{to_format}`

Converts a timestamp between epoch and ISO 8601 and between time zones. Use input format auto to have the format detected, and send the value now for the current time.

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| from_format | one of: auto, epoch, iso | yes |  |
| to_format | one of: epoch, iso | yes |  |

## Request body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| value | string | yes | The timestamp value to convert (or 'now' for current time) |
| from_format | string | no | Input format: 'epoch', 'iso', or 'now' (auto-detected if omitted) |
| to_format | string | no | Output format: 'epoch' or 'iso' (inferred if omitted) |
| tz | string | no | Output timezone (e.g., 'UTC', 'Europe/Lisbon', 'US/Eastern') (default `"UTC"`) |
| from_tz | string | no | Source timezone for ISO input (enables tz-to-tz conversion) |

## Example request

A request body that works, as JSON.

```json
{
  "value": "2026-03-13T09:00:00Z",
  "tz": "UTC"
}
```

## Response

The fields inside `data` of a successful response.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| original | string | yes | Original input value |
| converted | string | yes | Converted timestamp value |
| from_format | string | yes | Detected or specified input format |
| to_format | string | yes | Output format used |
| timezone | string | yes | Timezone used for conversion |
| from_timezone | string | no | Source timezone (when tz-to-tz conversion was used) |

## Example response

A real answer from the operation, as JSON. The fields in the table above are inside `data`.

```json
{
  "data": {
    "original": "2026-03-13T09:00:00Z",
    "converted": "1773392400",
    "from_format": "iso",
    "to_format": "epoch",
    "timezone": "UTC",
    "from_timezone": null
  },
  "errors": null,
  "meta": {
    "request_id": "d42ba581-0cea-4002-9228-076af119c7a1",
    "timestamp": "2026-10-27T07:19:42.011970Z",
    "version": "2026-03-26"
  },
  "pagination": null
}
```

## Responses

| Status | When it happens |
| --- | --- |
| 200 | Successful Response |
| 400 | The body respects the operation schema, but the use case rejected it. Each problem is one ApiError entry |
| 413 | The request is larger than the request size limit of the API allows |
| 422 | The body does not respect the operation schema. Each problem is one ApiError entry with the code validation_error |
| 500 | Something failed inside the server and was not an input problem. The same envelope, errors may be empty |

---
Source: https://skillfulsardine.com/developers/api/convert-timestamp/