Version: 1.0.0
Last Updated: 26th Jun, 2024

Introduction

Welcome to the Deep-Me API documentation for managing user posts in our application. This API allows you to create, read, update, and delete posts, as well as manage user registration and authentication. The API is designed to be intuitive and RESTful, making it easy to integrate with your application.

Authentication and Permissions

To ensure security and proper access control, some endpoints require specific permissions, which are granted through authentication tokens. These tokens are generated by the authentication endpoint and should be included in the header of API requests to endpoints that require permissions.

Base URL

The base URL for the API is https://api.deep-me.com/v1.

Rate Limiting

The API has a rate limit to prevent clients from making too many requests too quickly, and putting excessive strain on our server. If you exceed this limit, you will receive a 429 status code and will need to wait to make additional requests.

API endpoints

Method URL pattern Action Required permission
GET /v1/healthcheck Show application information
GET /v1/posts Show the details of all posts posts:read
POST /v1/posts Create a new post posts:write
GET /v1/posts/:id Show the details of a specific post posts:read
PATCH /v1/posts/:id Update the details of a specific post posts:write
DELETE /v1/posts/:id Delete a specific post posts:write
POST /v1/users Register a new user
PUT /v1/users/activated Activate a specific user
POST /v1/tokens/authentication Generate a new authentication token

Quick Start


# Register a new user
curl \
-X POST https://api.deep-me.com/v1/users \
-d '{ "name": "Mock User", "email": "mockuser@example.com", "password": "pa55word" }'

# Activate the user account
curl \
-X PUT https://api.deep-me.com/v1/users/activated \
-d '{ "token": "activation_mock_token" }'

# Create an authentication token
curl \
-X POST https://api.deep-me.com/v1/tokens/authentication \
-d '{ "email": "mockuser@example.com", "password": "pa55word" }'

# Use the token to access the API
curl \
-H 'Authorization: Bearer authentication_mock_token' \
https://api.deep-me.com/v1/posts

To quickly get started with the API, follow these steps:

  1. Register a new user using the Register User endpoint.

  2. Activate the user account using the Activate User endpoint.

  3. Create an authentication token using the Create Token endpoint.

  4. Use the authentication token to access the other endpoints in the API.

Register User


# Register a new user
curl \
-X POST https://api.deep-me.com/v1/users \
-d '{ "name": "Mock User", "email": "mockuser@example.com", "password": "pa55word" }'
            

Result example:

{
    "user": {
        "id": "57e23e26-4c40-4d72-9371-fd796e5116ec",
        "created_at": "2025-12-20T00:00:00Z"",
        "name": "Mock User",
        "email": "mockuser@example.com",
        "activated":false
    }
}

To create a new user account, make a POST request to the /v1/users endpoint. The user account will be created in a deactivated state, and an activation token will be sent to the user's email address.

Body Parameters

Field Type Description
name String Your username.
email String Your email.
password String Your password.

Activate User


# Activate the user account
curl \
-X PUT https://api.deep-me.com/v1/users/activated \
-d '{ "token": "activation_mock_token" }'
            

Result example:

{
    "user": {
      "id": "57e23e26-4c40-4d72-9371-fd796e5116ec",
      "created_at": "2025-12-20T00:00:00Z",
      "name": "Mock User"",
      "email": "mockuser@example.com",
      "activated": true
    }
}

To activate a user account, make a PUT request to the /v1/users/activated endpoint.

Body Parameters

Field Type Description
token String Token received in welcome mail.

Create Token


# Create Token
curl \
-X POST https://api.deep-me.com/v1/tokens/authentication \
-d '{ "email": "mockuser@example.com", "password": "pa55word" }'
            

Result example:

{
    "authentication_token": {
      "token": "authentication_mock_token",
      "expiry": "2024-07-07T13:38:24Z",
    }
}

To create an authentication token, make a POST request to the /v1/tokens/authentication endpoint.

Body Parameters

Field Type Description
email String Your email.
password String Your password.

List Posts


# List Posts
curl \
-H 'Authorization: Bearer authentication_mock_token' \
https://api.deep-me.com/v1/posts?title=Mock&content=This&authorEmail=mockuser@example.com&tags=mock,dummy&page=1&page_size=2&sort=created_at
            

Result example:
{
    "metadata": {
      "current_page": 1,
      "page_size": 2,
      "first_page": 1,
      "last_page": 1,
      "total_records": 2
    },
    "posts": [
        {
            "id": "0ac076a4-5046-4535-ba10-f204638ec5cb",
            "created_at": "2025-12-20T00:00:00Z",
            "title": "Mock Post (1)",
            "content": "This is the first mock post.",
            "tags": ["mock","dummy"]
        }, 
        {
            "id": "95de96a2-c8bb-45da-a7d9-b78ef4f4500c",
            "created_at": "2025-12-20T00:00:00Z",
            "title": "Mock Post (2)",
            "content": "This is the second mock post.",
            "tags": ["mock","dummy"]
        } 
    ]
}

To get list of posts, make a GET request to the /v1/posts endpoint.

Query Parameters

Field Type Description
title String (optional) A value to find post by title.
content String (optional) A value to find post by content.
authorEmail String (optional) A value to find post by author email.
tags String (optional) Some values separated by commas to find post by tag.
page Integer (optional) The page number to retrieve (used for pagination).
page_size Integer (optional) The number of items per page (used for pagination).
sort String (optional) The field by which to sort the results (e.g., "id", "title", "created_at", "-id", "-title", "-created_at").

Get Post


# Get Post
curl \
-H 'Authorization: Bearer authentication_mock_token' \
https://api.deep-me.com/v1/posts/:id 
            

Result example:

{
    "post": {
        "id": "0ac076a4-5046-4535-ba10-f204638ec5cb"",
        "created_at": "2025-12-20T00:00:00Z",
        "title": "Mock Post (1)",
        "content": "This is the first mock post.",
        "tags": ["mock","dummy"]
    }
}

To get the details of a specific post, make a GET request to the /v1/posts/:id endpoint

Path Parameters

Field Type Description
id String Post id.

Create Post


# Create Post
curl \
-H 'Authorization: Bearer authentication_mock_token' \
-X POST https://api.deep-me.com/v1/posts \
-d '{"title":"Mock Post (1)", "content": "This is the first mock post.", "tags":["mock","dummy"]}'
            

Result example:

{
    "post": {
      "id": "0ac076a4-5046-4535-ba10-f204638ec5cb",
      "created_at": "2024-07-06T13:38:24Z",
      "title": "Mock Post (1)",
      "content": "This is the first mock post.",
      "tags": ["mock","dummy"]
    }
}

To create a post, make a POST request to the /v1/tokens/authentication endpoint

Body Parameters

Field Type Description
title String Post title.
content String Post content.
tags String Post tags. tags must contain at least 1 element.

Update Post


# Update Post
curl \
-H 'Authorization: Bearer authentication_mock_token' \
-X PATCH https://api.deep-me.com/v1/posts/:id \
-d '{"title":"Mock Post (1) (updated)", "content": "This is the first mock post. (updated)", "tags":["updated"]}'
            

Result example:

{
    "post": {
        "id": "0ac076a4-5046-4535-ba10-f204638ec5cb (updated)",
        "created_at": "2024-07-06T13:38:24Z (updated)",
        "title": "Mock Post (1) (updated)",
        "content": "This is the first mock post. (updated)",
        "tags": ["updated"]
    }
}

To update a post, make a PATCH request to the /v1/posts/:id endpoint

Body Parameters

Field Type Description
title String Post title.
content String Post content.
tags String Post tags. tags must contain at least 1 element.

Path Parameters

Field Type Description
id String Post id.

Delete Post


# Delete Post
curl \
-H 'Authorization: Bearer authentication_mock_token' \
-X DELETE https://api.deep-me.com/v1/posts/:id
            

Result example:

{
    "message": "post successfully deleted"
}

To delete a post, make a DELETE request to the /v1/posts/:id endpoint

Path Parameters

Field Type Description
id String Post id.

Get App Info


# Get App Info
curl \
https://api.deep-me.com/v1/healthcheck
            

Result example:

{
    "status": "available",
    "system_info": {
        "environment": "production",
        "status": "available",
        "version": "-"
    }
}

To get app information, make a GET request to the /v1/healthcheck endpoint

Errors

The Deep-Me API uses the following error codes:

Error Code Meaning
400 the server cannot or will not process the request due to something that is perceived to be a client error.
401 invalid or missing authentication token.
403 your user account doesn't have the necessary permissions to access this resource.
404 the requested resource could not be found.
405 the method is not supported for this resource.
409 unable to update the record due to an edit conflict, please try again.
429 rate limit exceeded.