{
  "openapi": "3.1.0",
  "info": {
    "title": "areuworking Presence API",
    "version": "1.0.0",
    "summary": "Find out who is working and who is off, for any date range.",
    "description": "The Presence API exposes a single endpoint that returns presence information for the authenticated organization. Use it to sync Slack status, build internal dashboards, or give AI agents real-time team availability context.",
    "contact": {
      "name": "areuworking support",
      "email": "javi@areuworking.com",
      "url": "https://areuworking.com/api"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://app.areuworking.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/presence": {
      "get": {
        "summary": "Get team presence for a date range",
        "description": "Returns lists of team members who are working and who are off during the specified date range. Optionally filter by team. If no dates are supplied, the API defaults to today through the next 7 days.",
        "operationId": "getPresence",
        "tags": ["Presence"],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start date in ISO 8601 format (YYYY-MM-DD). Defaults to today.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-06-01"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End date in ISO 8601 format (YYYY-MM-DD). Must be on or after `from`. Defaults to 7 days after `from`.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2026-06-07"
            }
          },
          {
            "name": "team_id",
            "in": "query",
            "required": false,
            "description": "Optional team UUID to filter results.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "1c5dcf5e-cc63-4b3b-8eec-c3b6e8fd2d5d"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Presence information for the requested range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PresenceResponse"
                },
                "example": {
                  "from": "2026-06-01",
                  "to": "2026-06-07",
                  "team_id": null,
                  "team_name": null,
                  "in": [
                    {
                      "id": "71d0e1f8-7d4c-44f4-8d21-59fb04c353d3",
                      "name": "Alex Chen",
                      "email": "alex@example.com",
                      "avatar": null,
                      "team_id": "1c5dcf5e-cc63-4b3b-8eec-c3b6e8fd2d5d",
                      "team_name": "Engineering",
                      "timezone": "Europe/Madrid"
                    }
                  ],
                  "out": [
                    {
                      "id": "0465f18f-1c7d-48da-9838-77b0f86a7f92",
                      "name": "Sam Rivera",
                      "email": "sam@example.com",
                      "avatar": null,
                      "team_id": "6c2314cc-2e78-4f63-b019-f4a23e41cc0e",
                      "team_name": "Design",
                      "timezone": "Europe/London",
                      "leaves": [
                        {
                          "type": "holiday",
                          "start_date": "2026-06-03",
                          "end_date": "2026-06-07"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Pass your areuworking API key as a Bearer token. Generate keys in Settings -> API keys."
      }
    },
    "schemas": {
      "PresenceResponse": {
        "type": "object",
        "required": ["from", "to", "team_id", "team_name", "in", "out"],
        "properties": {
          "from": {
            "type": "string",
            "format": "date",
            "description": "Start of the queried range."
          },
          "to": {
            "type": "string",
            "format": "date",
            "description": "End of the queried range."
          },
          "team_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Requested team filter, if provided."
          },
          "team_name": {
            "type": ["string", "null"],
            "description": "Name of the requested team, if a team filter was provided and found."
          },
          "in": {
            "type": "array",
            "description": "Team members who are working during the range.",
            "items": {
              "$ref": "#/components/schemas/PresenceMember"
            }
          },
          "out": {
            "type": "array",
            "description": "Team members who are off during the range, partially or fully.",
            "items": {
              "$ref": "#/components/schemas/OutMember"
            }
          }
        }
      },
      "PresenceMember": {
        "type": "object",
        "required": ["id", "name", "email", "avatar", "team_id", "team_name", "timezone"],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique user identifier."
          },
          "name": {
            "type": "string",
            "description": "Display name."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "User email address."
          },
          "avatar": {
            "type": ["string", "null"],
            "description": "Avatar URL, if available."
          },
          "team_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Assigned team ID, if any."
          },
          "team_name": {
            "type": ["string", "null"],
            "description": "Assigned team name, if any."
          },
          "timezone": {
            "type": ["string", "null"],
            "description": "User timezone, if set."
          }
        }
      },
      "OutMember": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PresenceMember"
          },
          {
            "type": "object",
            "required": ["leaves"],
            "properties": {
              "leaves": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PresenceLeave"
                }
              }
            }
          }
        ]
      },
      "PresenceLeave": {
        "type": "object",
        "required": ["type", "start_date", "end_date"],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["holiday", "sick", "personal", "bank_holiday"],
            "description": "Type of leave."
          },
          "start_date": {
            "type": "string",
            "format": "date",
            "description": "Start of the absence."
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "description": "End of the absence."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["message"],
            "properties": {
              "message": {
                "type": "string",
                "description": "Human-readable error message."
              },
              "issues": {
                "type": "array",
                "description": "Validation issues, when available.",
                "items": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "array",
                      "items": {
                        "type": ["string", "number"]
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}