---
agentTools:
  projectIndex: https://urlhum.readme.io/llms.txt
---

# Introduction

Learn how to use UrlHum Rest APIs

UrlHum has very basic REST API at the moment.
The authentication is made via Bearer Token that identifies the user.

Users can create their own access tokens going in their profile section using the menu: **/profile/access-token**

Access Tokens don't expire. Users can see last used time, add new access tokens (giving them a name) and remove them.

When creating an access token, users will be provided with the plain token that will be visible **just that time**. Reloading or closing the page will result in the token lost and the user will need to create it again.

The only endpoint currently available is for creating a short url.

[block:api-header]
{
  "title": "Making requests"
}
[/block]

Every request must include the following headers:

**Content-Type: application/json**
**Accept: application/json**
**Authentication: Bearer {token}**

Replace *token* with your own token obtained previously.

Obviously the body of the request must be a *valid* JSON.

Every endpoint is actually prefixed with **/api/v1/**

[block:api-header]
{
  "title": "Handling errors"
}
[/block]

UrlHum responses vary based on the error generated.

[block:parameters]
{
  "data": {
    "h-0": "Status code",
    "h-1": "Error type",
    "h-2": "Reason",
    "0-0": "404",
    "0-1": "Endpoint not found",
    "0-2": "Using a non-existing endpoint",
    "1-0": "404",
    "1-1": "URL not found",
    "1-2": "Short URL in request doesn't exist",
    "2-0": "403",
    "2-1": "Forbidden",
    "2-2": "User Token is not allowed to perform this action",
    "3-0": "409",
    "3-1": "Parameters or generic error about the URL",
    "3-2": "You may have passed an invalid parameter. Read **message** response key to know the reason",
    "4-0": "500",
    "4-1": "Unhandled exception",
    "4-2": "Server error. Check the error logs.",
    "5-0": "401",
    "5-1": "Unauthenticated",
    "5-2": "Token is invalid."
  },
  "cols": 3,
  "rows": 6
}
[/block]