INCIDENsly 𝒘ebApp API Documentation

Postman collection → OpenAPI spec →

Introduction

Documentation for the INCIDENsly 𝒘ebApp API.

This API provides endpoints for managing incidents, comments, tags, and user administration. Authentication is handled via OAuth2 (Bearer token). Use the /login endpoint to obtain your token. All responses are returned in JSON format.

Quick Start

  1. Register a new user via the /register endpoint to create an account and obtain an API token.
  2. Use the /login endpoint to authenticate and receive an access token.
  3. Include the token in the Authorization header (e.g. Authorization: Bearer {YOUR_TOKEN}) for all subsequent requests to protected endpoints.
  4. Explore the available endpoints for managing incidences, comments, tags, and users.
  5. Refer to the endpoint documentation for details on request parameters, response formats, and example requests and responses.

Roles

  • user — Can manage their own incidents, comments, and tags.
  • admin — has additional access to user management.

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Authentication

Endpoints for user registration, login, logout and profile view.

Register a new user.

POST
http://127.0.0.1:8000
/api/v1/register

Create a new user account and returns an OAuth token.

Headers

Content-Type
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "http://127.0.0.1:8000/api/v1/register" \
    --header "Content-Type: application/json" \
    --data "{
    \"name\": \"New User\",
    \"email\": \"newuser@example.com\",
    \"password\": \"password123\",
    \"password_confirmation\": \"password123\"
}"
Example response:
{
    "data": {
        "id": 1,
        "name": "New User",
        "email": "newuser@example.com"
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}
{
    "message": "Unauthenticated."
}
{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "The email has already been taken."
        ]
    }
}

Login user.

POST
http://127.0.0.1:8000
/api/v1/login

Authenticate user with email and password, returns an OAuth token on success.

Headers

Content-Type
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "http://127.0.0.1:8000/api/v1/login" \
    --header "Content-Type: application/json" \
    --data "{
    \"email\": \"gbailey@example.net\",
    \"password\": \"|]|{+-\"
}"
Example response:

Logout user.

POST
http://127.0.0.1:8000
/api/v1/logout
requires authentication

Invalidate the user's current access token, effectively logging them out.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Example request: 
curl --request POST \
    "http://127.0.0.1:8000/api/v1/logout" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
    "message": "Logged out successfully"
}
{
    "message": "Unauthenticated."
}

Get current user profile.

GET
http://127.0.0.1:8000
/api/v1/me
requires authentication

Returns the authenticated user's profile information.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/me" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
    "data": {
        "id": 1,
        "name": "New User",
        "email": "newuser@example.com"
    }
}
{
    "message": "Unauthenticated."
}

Comments

Endpoints for managing comments on incidences, including listing, creating, viewing, updating, and deleting comments. Returns only root comments (parent_id = null) with their nested children.

List comments.

GET
http://127.0.0.1:8000
/api/v1/incidences/{incidenceId}/comments

Retrieve all root comments for a specific incidence, including their nested children.

URL Parameters

incidenceId
integer
required

The ID of the incidence.

Example:
1
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/incidences/1/comments"
Example response:
{
  "data": [
    {
      "id": 1,
      "body": "This is a comment",
      "user_id": 1,
      "incidence_id": 1,
      "parent_id": null,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "user": {...},
      "children": [
        {
          "id": 2,
          "body": "This is a reply",
          "user_id": 2,
          "incidence_id": 1,
          "parent_id": 1,
          "created_at": "2026-01-01T00:00:00Z",
          "updated_at": "2026-01-01T00:00:00Z",
          "user": {...},
          "children": [...]
        }
      ]
    }
  ]
}
{
    "message": "No query results for model [App\\Models\\Incidence]"
}

Create a new comment.

POST
http://127.0.0.1:8000
/api/v1/incidences/{incidenceId}/comments
requires authentication

Add a new comment to a specific incidence. The authenticated user will be set as the creator of the comment (user_id).

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json

URL Parameters

incidenceId
integer
required

The ID of the incidence to comment on.

Example:
1

Body Parameters

Example request: 
curl --request POST \
    "http://127.0.0.1:8000/api/v1/incidences/1/comments" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --data "{
    \"body\": \"\\\"This is a comment.\\\"\",
    \"parent_id\": 1
}"
Example response:
{
  "data": {
    "id": 1,
    "body": "This is a comment",
    "user_id": 1,
    "incidence_id": 1,
    "parent_id": null,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "user": {...}
  }
}
{
    "message": "Unauthenticated."
}
{
    "message": "The given data was invalid.",
    "errors": {
        "body": [
            "The body field is required."
        ],
        "parent_id": [
            "The parent_id must be a valid comment ID."
        ]
    }
}

View a single comment.

GET
http://127.0.0.1:8000
/api/v1/comments/{comment_id}

Get detailed information about a specific comment by its ID, including parent and children.

URL Parameters

id
integer
required

The ID of the comment.

Example:
1
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/comments/1"
Example response:
{
  "data": {
    "id": 1,
    "body": "This is a comment",
    "user_id": 1,
    "incidence_id": 1,
    "parent_id": null,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "user": {...},
    "children": [
      {
        "id": 2,
        "body": "This is a reply",
        "user_id": 2,
        "incidence_id": 1,
        "parent_id": 1,
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z",
        "user": {...},
        "children": [...]
      }
    ]
{
    "message": "No query results for model [App\\Models\\Comment]"
}

Update a comment.

PUT
http://127.0.0.1:8000
/api/v1/comments/{comment_id}
requires authentication

Update an existing comment by its ID. Only the creator of the comment can update it.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json

URL Parameters

id
integer
required

The ID of the comment to update.

Example:
1

Body Parameters

Example request: 
curl --request PUT \
    "http://127.0.0.1:8000/api/v1/comments/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --data "{
    \"body\": \"\\\"This is an updated comment.\\\"\"
}"
Example response:
{
  "data": {
    "id": 1,
    "body": "This is an updated comment",
    "user_id": 1,
    "incidence_id": 1,
    "parent_id": null,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "user": {...}
  }
}
{
    "message": "Unauthorized"
}

Delete a comment.

DELETE
http://127.0.0.1:8000
/api/v1/comments/{comment_id}
requires authentication

Delete an existing comment by its ID. Only the creator of the comment or an admin can delete it.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}

URL Parameters

id
integer
required

The ID of the comment to delete.

Example:
1
Example request: 
curl --request DELETE \
    "http://127.0.0.1:8000/api/v1/comments/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
    "message": "Comment deleted successfully"
}
{
    "message": "Unauthenticated."
}
{
    "message": "Unauthorized"
}
{
    "message": "No query results for model [App\\Models\\Comment]"
}

Incidences

Endpoints for managing incidences, including listing, creating, viewing, updating, and deleting incidences.

Create a new incidence.

POST
http://127.0.0.1:8000
/api/v1/incidences
requires authentication

Create a new incidence with the provided details. The authenticated user will be set as the creator of the incidence (user_id).

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "http://127.0.0.1:8000/api/v1/incidences" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --data "{
    \"title\": \"\\\"Server Down\\\"\",
    \"description\": \"\\\"The main server is not responding since 3 PM.\\\"\",
    \"status\": \"architecto\",
    \"priority\": \"architecto\",
    \"assigned_to\": 2,
    \"tags\": \"\\\"server, urgent, backend\\\"\"
}"
Example response:
{
  "data": [
    {
      "id": 1,
      "title": "Server Down",
      "description": "Main server not responding",
      "status": "open",
      "priority": "critical",
      "user_id": 1,
      "assigned_to": 2,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "user": {...},
      "assigned_user": {...},
      "tags": [...]
    }
  ]
}
{
    "message": "Unauthenticated."
}
[
    {
        "message": "The given data was invalid.",
        "errors": {
            "title": [
                "The title field is required."
            ],
            "description": [
                "The description field is required."
            ]
        }
    }
]

Update an incidence.

PUT
http://127.0.0.1:8000
/api/v1/incidences/{incidence_id}
requires authentication

Update an existing incidence by its ID. Only the creator of the incidence or an admin can update it.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json

URL Parameters

id
integer
required

The ID of the incidence to update.

Example:
1

Body Parameters

Example request: 
curl --request PUT \
    "http://127.0.0.1:8000/api/v1/incidences/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --data "{
    \"title\": \"\\\"Server Down - Updated\\\"\",
    \"description\": \"\\\"Main server not responding - Updated\\\"\",
    \"status\": \"\\\"in_progress\\\"\",
    \"priority\": \"\\\"high\\\"\",
    \"assigned_to\": 2,
    \"tags\": \"\\\"server, urgent, backend\\\"\"
}"
Example response:
{
    "data": [
        {
            "id": 1,
            "title": "Server Down - Updated",
            "description": "Main server not responding - Updated",
            "status": "in_progress",
            "priority": "high",
            "user_id": 1,
            "assigned_to": 2,
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": "2026-01-01T01:00:00Z"
        }
    ]
}
{
    "message": "Invalid request data. No query results for model [App\\Models\\Incidence]."
}
{
    "message": "Unauthenticated."
}
{
    "message": "Unauthorized"
}

Delete an incidence.

DELETE
http://127.0.0.1:8000
/api/v1/incidences/{incidence_id}
requires authentication

Delete an existing incidence by its ID. Only the creator of the incidence or an admin can delete it.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}

URL Parameters

id
integer
required

The ID of the incidence to delete.

Example:
1
Example request: 
curl --request DELETE \
    "http://127.0.0.1:8000/api/v1/incidences/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
    "message": "Incidence deleted successfully"
}
{
    "message": "Unauthenticated."
}
{
    "message": "Unauthorized"
}

List my incidences.

GET
http://127.0.0.1:8000
/api/v1/my-incidences
requires authentication

Retrieve incidences created by the authenticated user.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}

Query Parameters

status
string

Filter by status (open, in_progress, closed).

Example:
architecto
priority
string

Filter by priority (low, medium, high).

Example:
architecto
search
string

Search by title or description.

Example:
architecto
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/my-incidences?status=architecto&priority=architecto&search=architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
  "data": [...],
  "meta": {...}
}
{
    "message": "Unauthenticated."
}

List all incidences.

GET
http://127.0.0.1:8000
/api/v1/incidences

Retrieve all incidences with optional filters.

Query Parameters

status
string

Filter by status (open, in_progress, closed).

Example:
architecto
priority
string

Filter by priority (low, medium, high).

Example:
architecto
tags
string

Filter by comma-separated list of tag IDs.

Example:
1, 2, 3
search
string

Search by title or description. Examplo: server

Example:
architecto
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/incidences?status=architecto&priority=architecto&tags=1%2C+2%2C+3&search=architecto"
Example response:
{
  "data": [
    {
      "id": 1,
      "title": "Server Down",
      "description": "Main server not responding",
      "status": "open",
      "priority": "critical",
      "user_id": 1,
      "assigned_to": 2,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "user": {...},
      "assigned_user": {...},
      "tags": [...]
    }
  ]
}

View a single incidence.

GET
http://127.0.0.1:8000
/api/v1/incidences/{incidence_id}

Get detailed information about a specific incidence by its ID.

URL Parameters

id
integer
required

The ID of the incidence.

Example:
1
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/incidences/1"
Example response:
{
    "data": [
        {
            "id": 1,
            "title": "Server Down",
            "description": "Main server not responding",
            "status": "open",
            "priority": "critical",
            "user_id": 1,
            "assigned_to": 2,
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": "2026-01-01T00:00:00Z"
        }
    ]
}

Metrics

Endpoints for retrieving aggregated metrics and statistics about incidences, such as counts by status and priority.

List Metrics.

GET
http://127.0.0.1:8000
/api/v1/metrics
requires authentication

Retrieve aggregated metrics and statistics about incidences.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/metrics" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
  "data": {
    "by_status": {
      "open": [
        {"id": 1, "title": "Server Down", "status": "open", "priority": "critical", ...}
      ],
      "in_progress": [],
      "closed": []
    },
    "by_priority": {
      "low": [],
      "medium": [],
      "high": [...],
      "critical": [...]
    }
  }
}
{
    "message": "Unauthenticated."
}

Tags

Endpoints for managing tags, including listing, creating, viewing, updating, and deleting tags.

List all tags.

GET
http://127.0.0.1:8000
/api/v1/tags

Retrieve all tags with their associated users and incidences.

Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/tags"
Example response:
{
  "data": [
    {
      "id": 1,
      "name": "tag1",
      "user_id": 1,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "user": {...},
      "incidences": [...]
    }
  ]
}

Create a new tag.

POST
http://127.0.0.1:8000
/api/v1/tags
requires authentication

Create a new tag or reuse an existing one with the same name (case-insensitive). Uses firstOrCreate to ensure atomicity and prevent duplicates. Tag names are stored in lowercase to enforce case-insensitivity.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "http://127.0.0.1:8000/api/v1/tags" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --data "{
    \"name\": \"Server\"
}"
Example response:
{
  "data": {
    "id": 1,
    "name": "server",
    "user_id": 1,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "user": {...},
    "incidences": [...]
  }
}
{
    "message": "Unauthenticated."
}
{
    "message": "The given data was invalid.",
    "errors": {
        "name": [
            "The name field is required."
        ]
    }
}

View a single tag.

GET
http://127.0.0.1:8000
/api/v1/tags/{tag_id}

Get detailed information about a specific tag by its ID, including the user who created it and the incidences associated with it.

URL Parameters

id
integer
required

The ID of the tag.

Example:
1
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/tags/1"
Example response:
{
  "data": {
    "id": 1,
    "name": "server",
    "user_id": 1,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "user": {...},
    "incidences": [...]
  }
}

Update a tag.

PUT
http://127.0.0.1:8000
/api/v1/tags/{tag_id}
requires authentication

Update the details of an existing tag. Only the creator of the tag or an admin can update it.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Content-Type
Example:
application/json

URL Parameters

id
integer
required

The ID of the tag.

Example:
1

Body Parameters

Example request: 
curl --request PUT \
    "http://127.0.0.1:8000/api/v1/tags/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --data "{
    \"name\": \"Server\"
}"
Example response:
{
  "data": {
    "id": 1,
    "name": "server",
    "user_id": 1,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "user": {...},
    "incidences": [...]
  }
}
{
    "message": "Unauthenticated."
}
{
    "message": "Unauthorized"
}
{
    "message": "No query results for model [App\\Models\\Tag]"
}

Delete a tag.

DELETE
http://127.0.0.1:8000
/api/v1/tags/{tag_id}
requires authentication

Delete an existing tag. Only the creator of the tag or an admin can delete it. Note: This removes the tag from all associated incidences (pivot table).

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}

URL Parameters

id
integer
required

The ID of the tag.

Example:
1
Example request: 
curl --request DELETE \
    "http://127.0.0.1:8000/api/v1/tags/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
    "message": "Tag deleted successfully"
}
{
    "message": "Unauthenticated."
}
{
    "message": "Unauthorized"
}
{
    "message": "No query results for model [App\\Models\\Tag]"
}

Users

Endpoints for managing users, including listing all users, viewing a single user, retrieving a user's incidences, and deleting a user.

List all users.

GET
http://127.0.0.1:8000
/api/v1/users
requires authentication

Retrieve a list of all users.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/users" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
  "data": [
    {
      "id": 1,
      "name": "User Admin",
      "email": "admin@telsur.cl",
      "is_admin": true,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "name": "User no Admin",
      "email": "noadmin@telsur.cl",
      "is_admin": false,
      ...
    }
  ]
}
{
    "message": "Unauthenticated."
}
{
    "message": "Forbidden. Admin access required."
}

View a single user.

GET
http://127.0.0.1:8000
/api/v1/users/{id}
requires authentication

Get detailed information about a specific user by their ID.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}

URL Parameters

id
integer
required

The ID of the user.

Example:
1
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/users/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
    "data": {
        "id": 1,
        "name": "User Admin",
        "email": "admin@telsur.cl",
        "is_admin": true,
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z"
    }
}
{
    "message": "Unauthenticated."
}
{
    "message": "Forbidden. Admin access required."
}
{
    "message": "User not found."
}

Get user's incidences.

GET
http://127.0.0.1:8000
/api/v1/users/{id}/incidences
requires authentication

Retrieve all incidences created by or assigned to a specific user by their ID.

  • The creartor of the incidence is determined by the user_id field.
  • The assigned user is determined by the assigned_to field.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}

URL Parameters

id
integer
required

The ID of the user.

Example:
2
Example request: 
curl --request GET \
    --get "http://127.0.0.1:8000/api/v1/users/2/incidences" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
  "data": [
    {
      "id": 1,
      "title": "Server Down",
      "user_id": 2,
      "assigned_to": 2,
      ...
    },
    {
      "id": 3,
      "title": "Database issue",
      "user_id": 1,
      "assigned_to": 2,
      ...
    }
  ]
}
{
    "message": "Unauthenticated."
}
{
    "message": "Forbidden. Admin access required."
}
{
    "message": "No query results for model [App\\Models\\User]."
}

Delete a user.

DELETE
http://127.0.0.1:8000
/api/v1/users/{id}
requires authentication

Remove a specific user from the system. Only an admin can delete a user, and users cannot delete themselves.

Headers

Authorization
Example:
Bearer {YOUR_AUTH_KEY}

URL Parameters

id
integer
required

The ID of the user.

Example:
1
Example request: 
curl --request DELETE \
    "http://127.0.0.1:8000/api/v1/users/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}"
Example response:
{
    "message": "User deleted successfully."
}
{
    "message": "Unauthenticated."
}
{
    "message": "Forbidden. Admin access required."
}
{
    "message": "User not found."
}