NAV Navbar
cURL PHP Python JavaScript

Introduction

For users, Gigaaa will be a personal assistant. However, it also allows developers to extend its functionality by adding new features in the form of services. These features can then be made available to the gigaaa community. This documentation will provide an overview of what can be done as a developer within the gigaaa environment.

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Bugs and Security Vulnerabilities

We are happy to get every kind of feedback. If you feel something is missing, too complicated or makes no sense, please don't hesitate to contact us.

With both the documentation and the api being at an early stage, changes are inevitable. Most of these changes will happen in the background without any (big) impact on existing code, others will cause some breakage of existing code. We will of course try and reduce the amount of non-backwards-compatible changes to a minimum.

If you find bugs, come along unexpected server errors, or discover a security vulnerability, please send an e-mail to dev@gigaaa.com describing the issue. We will look into all issues as quickly as possible.

Roadmap

What is Gigaaa

// TODO

Getting started

Our entire architecture is following an RESTful API design pattern, giving you basic CRUD-Operations for most models. However, we break out of a strict application from time to time. This is due the fact, that Gigaaa is not just about handling static models, but an interactive environment, which allows you to do more than creating and modifying entities.

Authentication


# With shell, you can just pass the correct header with each request

curl "/api/v1/current-user" \
  -XGET \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/current-user', $options);


import requests

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

requests.get('/api/v1/current-user', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/current-user', options)
    .then((response) => {
       return response.json();
    })
    .catch((error) => {
       console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
  "id": 2521,
  "name": "Jane",
  "email": "jane@doe.com",
  "language_id": 83,
  "api_token": "6urUK43TvXwKrxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "block": 0,
  "created_at": "2019-08-15 17:25:31",
  "avatar_url": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback",
  "avatar_url_tiny": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback?size=tiny",
  "is_tester": false,
  "language": {/* Language Object */},
  "profile": {/* Profile Object */},
  "timestamp": "2019-08-19 11:57:06"
}

/api/v1/current-user GET

Our API endpoints require an authenticated user. Authentication is therefore the first step of building your own application with Gigaaa. Gigaaa uses OAuth 2.0, hence we recommend to use any of the available OAuth 2.0 enabled authorization libraries. There are countless different solutions, depending on your actual tech stack. Just make sure, that the package you chose already covers most of the following steps. In a best case scenario, you just need to provide a client_id and secret to authenticate users.

If all you want to do is authenticate yourself against our system, you can start by creating a "Personal Access Token" using our developer console and pass it with every request. Head over to https://console.gigaaa.com/authentication/personal-access-tokens and create a fresh token. You can always come back to this page to view or delete your tokens.

After you have created your token, you can choose how to pass the token to our endpoints as it fits your requirements best. You can authenticate requests by simply passing api_token with your data (mainly relevant for a POST and PUT) or as a query parameter for GET requests (?api_token=xxx). You can also add your token to your header.

Please note, that your access rights are limited. After your authentication, we will authorize each user's action against a given resource. So, for example, you can only delete resources you are supposed to, even though you are successfully authenticated.

We will update our authentication possibilities as the need for it grows. For now, the personal access token is enough to make use of the currently provided feature set. But as our environment grows, we will open up more possibilities.

Service Request Authorization

# With shell, you can just pass the correct header with each request
curl "/api/v1/users/2/services/24" \
  -XGET \
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "request_token": "uoG7vrxxxxxxxxxxxxxxxxxx" }'
<?php

$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ],
    'json' => [
        'request_token' => ''
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/services/24', $options);

import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'request_token': 'uoG7vrxxxxxxxxxxxxxxxxxx' }

requests.get('/api/v1/users/2/services/24', data=json.dumps(payload), headers=headers)


 // If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
 };

fetch('/api/v1/users/2/services/24', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your request is valid, the above command returns JSON structured like this:

{
    "exists": true,
    "is_core_service": 1,
    "user": [],
    "user_options": {
        "favorite_chocolate": "Banana Vanilla Ice Cream"
    },
    "timestamp": "2019-07-06 07:14:08"
}

If you want to make requests as a Gigaaa service, for example to make asynchronous requests using our Gigaaa talks first feature or to access service-related user information, you need to authenticate and authorize your service against our api, not just yourself as a user. So, additionally to your personal access token, you have to pass the service´s request_token with your request. You will obtain the token when you create the service and check it with an administrator account.

You can access the service token at any time when you call the service detail endpoint.

If your token is compromised, or you feel the need to change it, you can always do so by sending request_new_token = true along with a regular PUT update request. Please be aware that as soon as your requests go through, all requests holding the previous key will fail!

Pagination

When you access list views, they are most of the time too extensive to show all items at once. In those cases, we offer a simple pagination functionality. Just pass the current page and how many items you want to display per page and the results will change accordingly.

When we are dealing with list views, the results are wrapped by a data attribute.

{
    "current_page": 1,
    "data": [/* List of Conversations. */],
    "first_page_url": "https://api.gigaaa.link/api/v1/conversations?page=1",
    "from": 1,
    "last_page": 6,
    "last_page_url": "https://api.gigaaa.link/api/v1/conversations?page=6",
    "next_page_url": "https://api.gigaaa.link/api/v1/conversations?page=2",
    "path": "https://api.gigaaa.link/api/v1/conversations",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 108,
    "timestamp": "2019-08-02 13:20:19"
}

Request

Parameter Description Type Default
page The current page to display. Int 1
per_page How many items should be displayed per page. Int 20
order_by What attribute the results should be ordered by. Int 20
order_direction ASC or DESC Int 20

That's it

You are good to go to have a basic conversation with gigaaa. All you need is a valid token and sending and receiving messages to/from /api/v1/gigaaa-conversations. You can play around with it and try out different requests. However, Gigaaa gives you many more options to extent the network. Those options will be described in the following sections.

General Endpoints

Gigaaa offers some endpoints which are used across the entire application.

For example countries and languages for gigaaa services have centralized endpoints. Especially when dealing with relations between models, the id values are of importance.

Gigaaa Status


# With shell, you can just pass the correct header with each request

curl "/online" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/online', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/online', headers=headers)


let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
};

fetch('/online', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-16 15:45:11"
}

Check if the gigaaa system is online and operational.

/online GET

Response

Parameter Description Type
success Returns true, if api is online. Bool

Countries


# With shell, you can just pass the correct header with each request

curl "/api/v1/countries" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/countries', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/countries', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/countries', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "countries": [
        {
            "id": 3,
            "code": "AF",
            "name": "Afghanistan",
            "filter": 1,
            "name_translated": "Afghanistan"
        }
    ],
    "timestamp": "2019-08-16 15:46:37"
}

/api/v1/countries GET

Response

Parameter Description Type
success Returns true, if request was successful. Bool
countries Array of all country objects. Array
countries.*.id Unique Country Id. Int
countries.*.code Country Code. String
countries.*.name Country Name. String
countries.*.filter - Int
countries.*.name_translated Country Name in the country's native language. String

Languages


# With shell, you can just pass the correct header with each request

curl "/api/v1/languages" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/languages', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/languages', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/languages', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "languages": [
        {
            "id": 1,
            "description": "Afrikaans",
            "code": "af",
            "locale_code": "af",
            "locale_code_decimal": "1078",
            "language_file": 0
        }
    ],
    "timestamp": "2019-08-19 11:24:11"
}

/api/v1/languages GET

Response

Parameter Description Type
success Returns true, if request was successful. Bool
languages Array of all language objects. Array
languages.*.id Unique language ID. Int
languages.*.description Basically the language name. String
languages.*.code Language Code. String
languages.*.code_decimal Language in decimal form. String
languages.*.language_file - Int

Basic Stats


# With shell, you can just pass the correct header with each request

curl "/api/v1/basic-stats" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/basic-stats', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/basic-stats', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/basic-stats', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "registered_users_count": 19,
    "all_conversation_messages_count": 85,
    "gig_conversation_messages_count": 0,
    "gigs_all_count": 9317,
    "gigs_active_count": 17,
    "gigs_min_one_user_count": 3,
    "timestamp": "2019-09-10 13:17:31"
}

/api/v1/basic-stats GET

Response

Parameter Description Type
registered_users_count Number of registered users. Int
all_conversation_messages_count Number of all conversation messages. Int
gig_conversation_messages_count Number of all gig conversation messages. Int
gigs_all_count Number of all gigs. Int
gigs_active_count Number of all active gigs. Int
gigs_min_one_user_count Number of gigs with at least one user. Int

Server Date Time


# With shell, you can just pass the correct header with each request

curl "/api/v1/server-date-time" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' 

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/server-date-time', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/server-date-time', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
};

fetch('/api/v1/server-date-time', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "utc": "2019-08-16T14:08:55.527585Z",
    "date": "2019-08-16",
    "time": "16:08:55",
    "date_time": "2019-08-16 16:08:55",
    "time_zone": {
        "timezone_type": 3,
        "timezone": "Europe/Berlin"
    },
    "timestamp": "2019-08-16 16:08:55"
}

/api/v1/server-date-time GET

Response

Parameter Description Type
utc Coordinated Universal Time. String
date Date (YYYY.MM.DD) String
time Time (HH:MM:SS) String
date_time Date and time combined. String
time_zone Timezone Object with timezone properties. Object
time_zone.*.timezone_type Timezone Type. Int
time_zone.*.timezone Timezone Name. String

Gigaaa Conversations

Start a conversation


# With shell, you can just pass the correct header with each request

curl "/api/v1/gigaaa-conversations" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "text": "Inspire me" }'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ],
    'json' => [
        'text' => 'Inspire me.'  
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/gigaaa-conversations', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json',
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = { 'text': 'Inspire me.' }

requests.post('/api/v1/gigaaa-conversations', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    },
    body: JSON.stringify({'text': 'Inspire me.'})
};

fetch('/api/v1/gigaaa-conversations', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "actions": {
    "display_list": {
        "layout": "simple",
        "elements": [
            {
                "title": "Inspire me: Dr. Brad McLain at TEDxLincoln - YouTube",
                "body": "Nov 18, 2013 ... Learning changes us, sometimes deeply. When it transforms [...]",
                "url": "https://www.youtube.com/watch?v=hXJlVxKzQD8",
                "image_url": "https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcR5sTyY9tMDbKlPYm"
            }
        ]
    }
    },
    "expect_reply": false,
    "service_id": 98,
    "timestamp": "2019-08-20 12:35:31"
}

/api/v1/gigaaa-conversations POST

The most basic request is sending a text string to Gigaaa, where it gets interpreted and answered. All conversations are initially started with a simple text string (holding your request) send to our main api endpoint /api/v1/gigaaa-conversations. All new conversations are started by posting your request to this url, even if you send an answer to a follow-up question from Gigaaa. Gigaaa is smart enough to understand if your message belongs to an ongoing conversation or to start a new one.

Request

Parameter Description Type Required
text The language string the user wants to get answered. String True
context Context of where the request is coming from. For example, the in-app position of the user. String False
position Array with lat/long of current user position. Array False
position.lat Latitude value of current user position. Numeric Required if position.lng is present
position.lng Longitude value of current user position. Numeric Required if position.lat is present
speed Current moving speed of the user. Numeric False
service_environment_uuid Service Environment UUID String False

Response

Parameter Description Type
success Boolean, if the response was successfully or not. Bool
actions Nested array with all the actions the client should execute. For example, show a text string holding the answer, place audio, mute the phone, follow a link etc. For a complete list of possible action see our In-App Actions. Array
expect_reply If true, Gigaaa is expecting the user to send a follow-up answer. The next request send to gigaaa will be handled by the same service, hence allowing ongoing conversations between users and services. Bool
skip_scroll An in-app command. If true, the app will not scroll to bottom after a new message was received. This is particularly helpful when displaying long tables. Bool
service_id The service which handled the request. Int

Give feedback about received message

When Gigaaa sends you a message, you always have the possibility to let the system know, if the answer met your expectation based on a 1 to 5 scale.

Get all message ratings


# With shell, you can just pass the correct header with each request

curl "/api/v1/gigaaa-conversation-message-ratings" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/gigaaa-conversation-message-ratings', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/gigaaa-conversation-message-ratings', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/gigaaa-conversation-message-ratings', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

[
    {
        "id": 1,
        "rating": 5,
        "gigaaa_conversation_message_id": 1,
        "comment": "Aliquam suscipit illo occaecati.",
        "created_at": "2020-02-18 08:03:12",
        "updated_at": "2020-02-18 08:03:12"
    },
    {/* .. another Rating */}
]

/api/v1/gigaaa-conversation-message-ratings GET

Response

Parameter Description Type
id Unique rating ID Int
rating rating from 1 to 5 Int
gigaaa_conversation_message_id Conversation Message ID that the rating belongs to Int
comment comment added by user for the rating String

Create Rating for Message


# With shell, you can just pass the correct header with each request

curl "/api/v1/gigaaa-conversation-message-ratings" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ 
        "gigaaa_conversation_message_id": 33, 
        "rating": 5 
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ],
    'json' => [
        'gigaaa_conversation_message_id' => 33, 
        'rating' => 5
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/gigaaa-conversation-message-ratings', $options);


import json
import requests

headers = { 
    'Accept': 'application/json',
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = { 
    'gigaaa_conversation_message_id': 33, 
    'rating': 5 
}

requests.post('/api/v1/gigaaa-conversation-message-ratings', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }, 
    body: JSON.stringify({
        'gigaaa_conversation_message_id': 33,
        'rating': 5
    })
};

fetch('/api/v1/gigaaa-conversation-message-ratings', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "rating": 5,
    "gigaaa_conversation_message_id": 6,
    "updated_at": "2020-02-21 00:26:53",
    "created_at": "2020-02-21 00:26:53",
    "id": 6
}

/api/v1/gigaaa-conversation-message-ratings POST

Request

Parameter Description Type Required
gigaaa_conversation_message_id The message id you would like to rate. Please note, every message can only have one rating. If you try to submit a second one for the same message, the request will fail. Int True
rating Integer based rating from 1 (worst) to 5 (best). If you create a thumb up/down scenario, you might want to reduce your selections to 1 (thumbs down) and 5 (thumbs up) instead of giving user a full scale. Int True
commentary A free text field where users can add content to their rating. String False

Response

Parameter Description Type
rating rating from 1 to 5 Int
gigaaa_conversation_message_id Conversation Message ID that the rating belongs to Int
comment comment added by user for the rating String
id Unique rating ID Int

Receive a rating


# With shell, you can just pass the correct header with each request

curl "/api/v1/gigaaa-conversation-message-ratings/33" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/gigaaa-conversation-message-ratings/33', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/gigaaa-conversation-message-ratings/33', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/gigaaa-conversation-message-ratings/33', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 3,
    "rating": 2,
    "gigaaa_conversation_message_id": 3,
    "comment": "Qui magni eligendi magnam alias.",
    "created_at": "2020-02-18 08:03:12",
    "updated_at": "2020-02-18 08:03:12"
}

/api/v1/gigaaa-conversation-message-ratings/{conversationMessageId} GET

Response

Parameter Description Type
id Unique rating ID Int
rating rating from 1 to 5 Int
gigaaa_conversation_message_id Conversation Message ID that the rating belongs to Int
comment comment added by user for the rating String

Update a rating


# With shell, you can just pass the correct header with each request

curl "/api/v1/gigaaa-conversation-message-ratings/27182" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "rating": 3 }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'json' => [
        'rating' => 3
    ]   
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/gigaaa-conversation-message-ratings/27182', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'rating': 3 }

requests.put('/api/v1/gigaaa-conversation-message-ratings/27182', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }, 
    body: JSON.stringify({

    })
};

fetch("/api/v1/gigaaa-conversation-message-ratings/27182", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-02 18:38:45"
}

/api/v1/gigaaa-conversation-message-ratings/{conversationMessageId} PUT

Response

Parameter Description Type
success True, if rating was deleted successfully. Bool

Delete a rating


# With shell, you can just pass the correct header with each request

curl "/api/v1/gigaaa-conversation-message-ratings/27182" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/gigaaa-conversation-message-ratings/27182', $options);


import requests

headers = { \
    'Accept': 'application/json', \
    'Content-Type': 'application/json', \
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
}

requests.delete('/api/v1/gigaaa-conversation-message-ratings/27182', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/gigaaa-conversation-message-ratings/27182", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-02 18:38:45"
}

/api/v1/gigaaa-conversation-message-ratings/{conversationMessageId} DELETE

Response

Parameter Description Type
success True, if rating was deleted successfully. Bool

Services

A Gigaaa Service is like a feature of the Gigaaa voice assistant. Every time someone speaks to Gigaaa, a service is triggered. This service then processes the input and creates the answer. Imagine Gigaaa by itself as an empty network, which is receiving requests and forwarding it to different services. Gigaaa alone has no ability to serve requests.

A Gigaaa service can be anything. Starting from a little "time service", which responses to user requests with the current time. It can also be a shopping service, guiding a user through a complex order and payment process using only the voice feedback.

Our Gigaaa architecture does all the heavy lifting for you. It allows you to easily add your service to the Gigaaa environment where it can be accessed by our community.

Each service needs to be added to our system to be available to the Gigaaa community. We call that the global service stack. For a user to use your service, they must add it to their personal service stack.

Terminology

Parameter Description
Service A service is a single user request receiving entity. It receives a trigger sentence, processes it and gives a response back to the user.
Global Service Stack The global service stack includes all services of gigaaa. No matter if a user is actually using it or not. Compare it to all apps in an application store.
Personal Service Stack The personal service stack includes services that the user is actually using. Services can either be added by default or manually activated by the user.
Core Service Core services are regular services, but they are developed and maintained by Gigaaa or other trusted groups. They are enabled for every user by default and can't be disabled. They mostly contain general and often used features, such as weather forecasts, checking the calendar or ordering a cab.
Trigger Sentences To know, when a specific service should actually handle a user request, trigger sentences come into play. They can be single words, word groups or entire sentences. They can be plain and simple, contain variables and placeholders or/and variations. When a user requests matches with a service trigger sentence, the requests is forwarded to that service.
Sentence Database The sentence database is a tool to manage trigger sentences. It is only used for internal services and allow the adding, testing and even translating of trigger sentences.
Conversation Framework After a user sends a requests, Gigaaa identifies the best service to handle it. The request is then forwarded to the service, which now needs to get activate and process the request. How the service handles it is entirely up to its developers. What happens behind the scenes does not affect the compatibility to Gigaaa, as long as it can receive and understand the request format and response back in our format. Depending on the coding language and how the developers handle the service, there are already countless turnkey solutions to handle the conversation flow. While we don't name any specific solutions, we found pretty stable free and open source solutions which allow scaling and rapidly get things up and running.

What cannot be a service and what are the limitations?

Right now, services face some limitations. First and biggest limitation is that your response needs to fit in one of our templates. Of course, a voice assistant should mainly be driven by speech, which can be a simple language string. But it is likely, that a service also has some structured or visualized content. We have designed our templates with flexibility in mind to enable a wide range of use cases. For example, we have cards, tables, lists, images, plain content and so on. But you will not be able to render pure HTML in your responses. Also, you cannot play any sort of videos without redirecting outside of Gigaaa. Gigaaa is a cross-device assistant, but some content types simply do work better on computers than on smart watches. Always keep in mind, to make your service as accessible as possible.

Next important note is, you will need some sort of hosting environment and keep it running at all times, for example, using a simple VPC. All you need to register in Gigaaa is your endpoint server where we will forward requests each time your service is triggered. We do not host your service! If your service goes offline and our system can't reach it, we will lower it's health status until you trigger a new health check manually. Which brings us to another important side note, keep your response time as low as possible, since we have very strict rules on timeouts. If you service is not responding within 3000 milliseconds, we will cancel it. The reason for these strict rules is because a conversation should feel natural and a delayed response breaks this natural feel.

Also, keep in mind that Gigaaa is at a very early development stage. We try to catch up with all requirements, but we are not there yet and we cannot ensure a complete consistent development experience across all endpoints. Therefore, we greatly appreciate all sorts of feedback and bug reports.

Service Users

Each service has two user groups.

What are core services and what distinguishes them?

Our environment aims at having as many developers as possible contributing to our global service stack. However, Gigaaa will also provide services by itself. Those services will be essential in the beginning, but also cover all basic needs in a future development phase. Our core services are mainly built inside the same architecture as all other services, with all the same possibilities and borders. We mainly try to improve our main system and let all developers participate in improvements instead of having a dual solution which gives us advantages over others. However, there are some crucial differences.

What else to know about services

Gigaaa is not involved with what happens inside a service. After we detect the intent of a request, we will forward the request in a structured manner to the service and relay the response from the service back to the user.

Service Permissions

From time to time services need more information about the user than just the pure language string. For example, the current location, local time or specific profile information, such as the email address. Gigaaa does not access any user information without explicit consent from the user. Therefore, services need to declare upfront if, why, and which information they want to receive to the user. If a permission is granted, the corresponding information will be forward to the service each time it is triggered. While Gigaaa provides a pre-defined set of permissions to which any developer can request access, any specific permission requests must be explained individually.

Service Settings

As a service gets bigger, it is likely that is outgrows a one-size-fits-all settings approach. To make it a little easier for users to keep track of all settings for different services, we allow service settings to be stored in our database. Settings can cover all general and personal details you want or need to operate a service properly. Users and the service itself can read, write, and update the database while the service is still active. Our clients provide a simple graphical interface for users to keep track of all stored settings.

Service Categories

Every service can be attached to one or more service categories.

How Can Users Use My Service?

For a user to be able to use a specific non-core service, he or she first needs to activate the service using any client with service managing capabilities, such as our iOS and Android app.

Also see Service Users for more information.

Service Development

The Gigaaa environment can easily be extended with new services. The development can roughly be separated into two parts.

  1. All actions happen on Gigaaa servers, before your service is actually hit and after we got your response back. This part needs to follow strict guidelines and is described in this section.
  2. Everything that happens in between the moment we hit your service and receive back a response is up to your service.

For your service to run smoothly you will in most cases need some information from other Gigaaa API endpoints. Such as country_ids, language_ids, and other user information. So make sure you check out our Open Endpoints.

You should start with testing your service in a local environment. After your service works there, follow this guide on how to add a service to our environment and make it accessible for the entire Gigaaa community.

Request Lifecycle

The lifecycle of user requests looks typically like that.

  1. Record a voice stream and transform it into a text string. This step is optional and must at this time performed individually by each client, since we don't offer any public endpoint to do so. Gigaaa only processes a text string. See Gigaaa Conversation, transcribe, the workflow may vary based on the used client.
  2. Send the request from the client to the Gigaaa server.
  3. Gigaaa server shall recognize the intent and structure of the received language string (Natural Language Understanding - NLU).
  4. Identify the appropriate service based on the intent and services the user has activated.
  5. Forward the structured data to correct service for processing.
  6. The service will pass the answer back to Gigaaa.
  7. Gigaaa will validate the response and forward it to the user.

Basic Service Structure and Parameters

Every service consists of some elementary parts. Most of them need to be defined when you add your service to Gigaaa.

Parameter Description Type Required
trigger_sentences An array of all sentences in all languages you want to trigger your service. Please see our section about the format requirements. If left empty, we will regularly crawl your endpoint under /gigaaa/sentences?gigaaa_service_id={gigaaaServiceId} to receive this data. Someone might prefer it to keep the trigger_sentences more tightly coupled to the service to make changes quickly. JSON / Null True
example_sentences Examples of your trigger sentences so the user knows how your service will work. JSON / Null False
auto_translate If you add more "languages" than you offer trigger_sentences for, you can choose to let our system automatically translate the missing ones. Bool False
endpoint The root endpoint under which our network communicates with your machine. You must provide a secure endpoint (https). URL True
id Your unique service id. Provided by Gigaaa. Int False
status Indicator of what went wrong (if anything) with your service. Int False
health_check_at Last time our bot checked your service. Timestamp False
core_service Indicator that shows whether or not your service is a core service. Bool (tinyInt) False
countries List of countries (country-ids) from which you want your service to be accessible. To learn the correct country-id for a particular country, please refer to our countries-endpoint. Array False
languages List of languages (language-ids) in which you wish to offer your service. To learn the correct language-id for a particular language, please refer to our languages-endpoint. Array False
options List of options (option-ids) you want users to fill. Please check the corresponding endpoint to learn the correct option-id for a particular option. Array False
permissions List of all request permissions. Please check our permissions endpoint and to learn the correct ids. Array False
categories An array of category ids. Array False
translations An array with all translations for the service's title and description. Array True

Special notes - For a service to have a good health status, at least one country, one language and a valid trigger sentence have to be accessible to our community. - If you provide multiple services using the same endpoint, you must respond to the right content for the requested service based on the gigaaa_service_id. - Please make sure you pass arrays (and not objects) as your nested sentences. We noticed that in many cases developers find it hard to distinguish and/or control the output. Since we need one format to work with, we will transform objects into arrays.

The Service endpoints, as of most of Gigaaa API, follow a RESTful design pattern. Thus, you can use all CRUD operations.

Create new service


# With shell, you can just pass the correct header with each request

curl "/api/v1/services" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{
          "trigger_sentences": 
              [ 
                  { 
                      "language_code": "en", 
                      "trigger_sentences": [ 
                          { 
                              "sentence": "What will the weather be like tomorrow", 
                              "intent": "weather_forecast", 
                              "entities": { 
                                  "day": "tomorrow" 
                              } 
                          } 
                      ], 
                      "negative_trigger_sentences": [ 
                          "I feel a bit under the weather" 
                      ] 
                  } 
              ], 
          "translations": [
              {
                  "title": "Weather Service", 
                  "locale": "en"
              }
          ],
          "endpoint": "https://www.example.com", 
          "countries": [57, 233], 
          "languages": [12007, 12008] 
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'trigger_sentences' => [
            [ // Mulitple Nestings for different languages
                'language_code'              => 'en',
                'trigger_sentences'          => [
                    [
                        'sentence' => 'What will the weather be like tomorrow',
                        'intent'   => 'weather_forecast',
                        'entities' => [ 
                           'day'   => 'tomorrow'
                        ]
                    ], // ... more trigger sentences
                ],
                'negative_trigger_sentences' => [ // Optional
                    'I feel a bit under the weather'
                ],
            ]
        ],
        'translations' => [
            'title' => 'Weather Service', 
            'locale' => 'en'
        ],
        'endpoint'          => 'https://www.example.com',
        'countries'         => [57, 233],
        'languages'         => [12007, 12008],
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/services', $options);


import json
import requests

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = {
    'trigger_sentences': [
        { 
            'language_code': 'en', 
            'trigger_sentences': [ 
                { 
                    'sentence': 'What will the weather be like tomorrow', 
                    'intent': 'weather_forecast', 
                    'entities': { 
                        'day': 'tomorrow' 
                    } 
                } 
            ], 
            'negative_trigger_sentences': [
                'I feel a bit under the weather'
            ] 
        } 
    ], 
    'translations': [
        {
            'title': 'Weather Service', 
            'locale': 'en'
        }
    ],
    'endpoint': 'https://www.example.com', 
    'countries': [57, 233], 
    'languages': [12007, 12008] 
}

requests.post('/api/v1/services', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "trigger_sentences": [
            {
                "language_code": "en",
                "trigger_sentences": [
                    {
                        "sentence": "What will the weather be like tomorrow",
                        "intent": "weather_forecast",
                        "entities": { 
                            "day": "tomorrow"
                        }
                    }
                ],
                "negative_trigger_sentences": [
                    "I feel a bit under the weather"
                ]
            }
        ],
        "translations": [
            {
               "title": "Weather Service",
               "locale": "en"            
            }
        ],
        "endpoint": "https://www.example.com",
        "countries": [57, 233],
        "languages": [12007, 12008]
    })
};

fetch("/api/v1/services", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 207,
    "request_token": "Gd5T9IIxxxxxxxxxxxxxxxxxxx",
    "added_to_current_user_stack": false,
    "short_description": "This is a weather service.",
    "timestamp": "2018-07-24 14:30:14",
    "created_at": "2018-07-24 14:30:14",
    "updated_at": "2018-07-24 14:30:14"
}

/api/v1/services POST

To create a new service, you must pass all required attributes and relationships. You will be automatically added as a user organizing this service.

To add/remove categories from a service, simply add an array filled with all category ids to your POST or PUT request, when creating or updating your service.

After the service is created, it can take a little while until it is fully responsive in our system. After that, whenever a user submits one request which matches with the trigger sentences you have defined, your service will receive the request from us in a structured fashion.

Remember: A user needs to have your service added to his/her personal service stack, to be able to use it, unless you have registered a new core service.

Request

Parameter Description Type Required
endpoint Endpoint of your service. URL True
trigger_sentences Array with trigger sentences of your service. Array False
trigger_sentences.*.language_code Language Code of the trigger sentences. String False
trigger_sentences.*.trigger_sentences Array with trigger sentences. Array False
trigger_sentences.*.trigger_sentences.*.sentences One specific trigger sentence. String False
trigger_sentences.*.trigger_sentences.*.intent Intent of the sentence. String False
trigger_sentences.*.trigger_sentences.*.entities Object with entity properties. Object False
trigger_sentences.*.trigger_sentences.*.entities.* Properties that fit the sentence above. String False
trigger_sentences.*.negative_trigger_sentences Array with negative trigger sentences. Array False
trigger_sentences.*.negative_trigger_sentences.* Negative trigger sentence. String False
auto_translate If you add more "languages" than you offer trigger_sentences for, you can choose to let our system automatically translate the missing ones. Bool False
published Decides whether your service is published or not. Int False
countries Array with IDs of all supported countries. Array False
countries.* Country ID. Int False
languages Array with IDs of all supported languages. Array False
languages.* Language ID. Int False
categories Array with IDs of all service categories. Array False
categories.* Service Category ID. Int True
permissions Array with all service permissions. Array False
permissions.*.id Permission ID. Int True
permissions.*.reason Reason why the service needs this permission. String False
options Array with all service options. Array False
options.*.id Option ID. Int True
options.*.label Label for the options field. String True
options.*.help_text Optional help text, can be used for explanation purposes. String False
translations Array with all translations. Array True, at least one translation.
translations.*.title Title of your service. String True
translations.*.description Description of your service. String False
translations.*.locale Locale of the title and description. String True
translations.*.example_sentences Array with example sentences of how to use your service. Array False
translations..example_sentences. Example sentence. String False

Valid Locale Codes

Locale
de
en
ru
es
fr
ar
tr

Response

Parameter Description Type
id Unique service ID. Int
request_token Token is used for future interactions with your service. String
added_to_current_user_stack Determines, whether the services was added to the current users service stack. Bool
short_description Short description of the service. String

Get a service


# With shell, you can just pass the correct header with each request

curl "/api/v1/services/204" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/services/204', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/services/204', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/services/204", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 207,
    "title": "Weather Service",
    "description": null,
    "intent": "intent",
    "endpoint": "https://www.example.com",
    "trigger_sentences": [
        {
            "language_code": "de",
            "trigger_sentences": [
                {
                    "sentence": "What will the weather be like tomorrow",
                    "intent": "weather_forecast",
                    "entities": {
                        "day": "tomorrow"
                    }
                }
            ],
            "negative_trigger_sentences": [
                "I feel a bit under the weather"
            ]
        }
    ],
    "trigger_sentences_hash": null,
    "priority": 0,
    "published": 0,
    "core_service": 0,
    "status": 0,
    "auto_translate": 0,
    "block": 0,
    "health_check_at": null,
    "created_at": "2019-07-24 16:35:20",
    "updated_at": "2019-07-24 16:35:20",
    "added_to_current_user_stack": false,
    "short_description": "",
    "countries": [],
    "permissions": [],
    "options": [],
    "languages": [],
    "categories": [],
    "users_organizing_this_service": [],
    "timestamp": "2019-07-24 16:51:50"
}

/api/v1/services/{id} GET

After your service is posted to our database, you can always access it. The result will be displayed together with some basic information about the relations, such as the organizing users, the languages, options and permissions.

The overall information you receive on a service differ based on your access role. For example, values regarding the service health status, the priority or the endpoint are not public.

Response

Parameter Description Type
id Unique ID of your service. Int
endpoint Endpoint of your service. URL
intent - String
published Publication status of your service. Int
core_service Determines, if your service is a core service. Int
status Health status of your service. Int
auto_translate If you add more "languages" than you offer trigger_sentences for, you can choose to let our system automatically translate the missing ones. Int
block Determines, if the resource is blocked. Int
added_to_current_user_stack True, if the current user has the service added to its own stack. Bool
short_description Shorter description of your service. String
countries Array with countries. Array
permissions Array with permissions the service has. Array
options Array with all options of the service. Array
languages Array with all languages the service supports. Array
categories Array with all service categories. Array
translations Array of translations. Array
users_organizing_this_service Array with all users that organize the service. Array

Update a service


# With shell, you can just pass the correct header with each request

curl "/api/v1/services/207" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "endpoint": "https://www.weatherservice.com" }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'endpoint' => 'https://www.weatherservice.com',
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/services/207', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'endpoint': 'https://www.weatherservice.com' }

requests.put('/api/v1/services', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "endpoint": "https://www.weatherservice.com",
    })
};

fetch("/api/v1/services/207", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your update process was successful, your will get a confirmation like that:

{
    "status": true,
    "timestamp": "2018-07-24 14:30:14"
}

/api/v1/services/{id} PUT

You can edit a service and its relation at any time. Just pass the parameter you would like to change.

Request

Parameter Description Type
request_token Token is used for future interactions with your service. String
endpoint Endpoint of your service. URL
trigger_sentences Array with trigger sentences of your service. Array
trigger_sentences.*.language_code Language Code of the trigger sentences. String
trigger_sentences.*.trigger_sentences Array with trigger sentences. Array
trigger_sentences.*.trigger_sentences.*.sentences One specific trigger sentence. String
trigger_sentences.*.trigger_sentences.*.intent Intent of the sentence. String
trigger_sentences.*.trigger_sentences.*.entities Object with entity properties. Object
trigger_sentences.*.trigger_sentences.*.entities.* Properties that fit the sentence above. String
trigger_sentences.*.negative_trigger_sentences Array with negative trigger sentences. Array
trigger_sentences.*.negative_trigger_sentences.* Negative trigger sentence. String
auto_translate If you add more "languages" than you offer trigger_sentences for, you can choose to let our system automatically translate the missing ones. Bool
published Decides whether your service is published or not. Int
countries Array with IDs of all supported countries. Array
countries.* Country ID. Int
languages Array with IDs of all supported languages. Array
languages.* Language ID. Int
categories Array with IDs of all service categories. Array
categories.* Service Category ID. Int
permissions Array with all service permissions. Array
permissions.*.id Permission ID. Int
permissions.*.reason Reason why the service needs this permission. String
options Array with all service options. Array
options.*.id Option ID. Int
options.*.label Label for the options field. String
options.*.help_text Optional help text, can be used for explanation purposes. String
translations Array with all translations. Array
translations.*.title Title of your service. String
translations.*.description Description of your service. String
translations.*.locale Locale of the title and description. String
translations.*.example_sentences Array with example sentences of how to use your service. Array
translations..example_sentences. Example sentence. String

Response

Parameter Description Type
status True, if updating the service was successful. Bool

Delete a service


# With shell, you can just pass the correct header with each request

curl "/api/v1/services" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/services/204', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/services/208', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/services/204", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "status": true,
    "timestamp": "2019-07-24 16:51:50"
}

/api/v1/services/{id} DELETE

After you have added a service, you can always edit or delete it. Send a DELETE request to remove your service.

Changes should in most cases take effect within minutes. However, the same processing cycle as for adding new services is responsible for updates which can take up to a few hours until changes are in place.

When you delete a service, be aware, it can't be undone. All data and relations will be lost forever. If you need to backup any data, make sure you do so before deleting a service.

Response

Parameter Description Type
status True, if deleting the service was successful. Bool

Which ChatBot / Conversation Framework to Use

Our goal is to work with all available programming languages and framework solutions. This is possible since we actually send our requests in a pretty simple format and expect the response back to follow a simple layout as well. What happens between the request and response does not affect the Gigaaa environment. You can theoretically work with any solution or simply receive and respond without using any framework at all. Practically, there are some limits you should consider.

It is highly recommended, that no matter which framework you use, you make sure it is capable of having conversations with multiple question-answer sequences by somehow maintaining the user's session/state between the requests.

One of the more complex obstacles to tackle is the overall performance. We follow a strict 2 - 3 second policy on service responses. If we don't receive any response, we will simply cancel the request. On top of that, we will deactivate the service until the health status gets re-evaluated by our system. This procedure usually takes just minutes, but it can actually take up to 24 hours. To prevent your service from being temporally de-indexed make sure that no matter what kind of request hits your service, it will always perform within these strict policy rules even if multiple users make use of it at the same time.

How to Structure Your Services

As said earlier, we don't have any requirements on how you structure one or multiple services behind the curtain. As long as you can handle our request and serve a proper response, everything is fine.

However, there are several points you might want to consider. We strongly recommend you to follow some kind of micro-service architecture bound together by one main system which handles the shared business logic. One core system, a framework or CMS you like which handles the authentication, authorization, processes the logic to maintain conversations state machine, manages your routes, and so on. It should be built as a stand-alone solution, which does not require any (Gigaaa) services to work.

On top of that, you create one self-containing package per service. This package will be added to your dependency stack. Every service should again be working on its own, requiring your core system to handle the shared logic but not any other service.

Special notes for core service

If you want to develop internal services, we have to manually verify your user account. Please contact us so we can whitelist your account. After that, you can change your service status by passing core_service = 1 when you create or update your service.

Hosting

Regarding on how to host your service you usually have a wide range of options. We don't want to restrict these too much, however, we still need to define a minimum acceptable structure. All in all we have a simple rule for now: Your service, your server. Most of our resources are hosted on Amazon AWS, we keep that approach also for internal services. We gladly provide you with a VPS, an EC2 instance, a database and all you need, which you can then manage. It is your responsibility to keep it alive and safe.

Those servers will never be coupled very tightly to our core system. In a worst case scenario: If they crash, they will make some services unavailable for a moment, but never affect any other outside service or the core system.

If you maintain a core service server, it can probably be reached from our trusted environment. That means, don't waste valuable request time in repeatedly validating the user request. This happens before the request reaches your service. For example, when you receive a request holding a user_id, you can be sure that we already validated the corresponding user token. If something is unclear on what to validate and what not, please contact us.

Service Relationships

Each service has relationships to various other entities such as countries, languages, permissions, and options. Most of the relationships are optional and can simply be added by posting an array holding the relationships ids. Please have a look at the corresponding endpoints to find the right related ids and add them to your create or update request.

While this is true for most relationships, some require a little more work to be done. Please see the following part.

For all relationships, there is an all or nothing rule for now. When you update a relationship, for instance, the service permissions, make sure to always pass all permissions at once. We always sync your values and do not attach or detach them separately. So, if you have two requested permission and want to add an additional one, you need to send all three permissions with your PUT request.

Service Permissions

# With shell, you can just pass the correct header with each request
curl "/api/v1/service-permissions" \
  -XGET \
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "request_token": "uoG7vrxxxxxxxxxxxxxxxxxx" }'
<?php

$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ],
    'json' => [
        'request_token' => 'uoG7vrxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/service-permissions', $options);

import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'request_token': 'uoG7vrxxxxxxxxxxxxxxxxxx' }

requests.get('/api/v1/service-permissions', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/service-permissions', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your request is valid, the above command returns JSON structured like this:

{
    "data": [
        {
            "id": 1,
            "name": "location",
            "description": "<p>Services can access and will receive the device location</p>",
            "core_only": 0
        },
        {
            "id": 2,
            "name": "push_requests",
            "description": "<p>This service is allowed to send self-defined push requests to the users device.</p>",
            "core_only": 0
        },
        {
            "id": 3,
            "name": "access_email",
            "description": "<p>This service is allowed to see users email address.</p>",
            "core_only": 0
        }
    ],
    "timestamp": "2019-07-06 11:08:00"
}

/api/v1/service-permissions GET

Gigaaa services are built around user consent. At the very beginning stands a user adding a specific service to his individual service stack. This allows a user to trigger a service. But it does not end there. Services may profit from users or even require users to share additional information. One example would be the current location. If you run a navigation service, you might want to access it to guide a user from their current whereabouts. But it also applies to a wide range of data, such as emails, phone numbers, or saved addresses; just to name a few. While it is always possible for a service to (re-)request particular pieces of information itself, it may be unnecessary. Many pieces of information have already been added from the user to their Gigaaa profile.

For a service to gain access, we implemented a simple and transparent way to request permissions and let users know about which pieces and with whom information is shared. For you as a developer, you simply add the required permissions to your service.

First, check out which permissions are available (endpoint /api/v1/service-permissions). While there is just a limited number of permissions available right now, it will quickly grow in the future. Please pay attention to the core_only column. If true, it can only be used by core services.

Secondly, add the desired permissions to your service. You can either add them directly when you first create your service or add/remove them later on by adding the parameters to your post request.

When you work with user data it is a good rule of thumb to request as little data as possible. You always have the possibility to add more permissions to your service later on, if you feel something is missing. When you add a service, you can optionally fill out the reason column per requested permission to give users a greater understanding of why you are requesting a certain piece of data.

When you add permissions to your service, the proper way to access the related data will depend of specific information. For instance, device related pieces of information are mostly sent with each user request under the extra key. For now, this applies mainly to GPS location data. If you request permission to receive additional information from the user, such as phone numbers or email addresses, you will find those pieces of data when you access the user using the correlated endpoint.

If you decide to add optional permissions to your service, you are very welcome to do so. Of course, you don't face any limitations on how many permissions you request. Simply add an array with the following format to your request:

Response

Parameter Description Type
id Unique permission ID. Int
name Permission name. String
description Description of the permission. String
core_only True, if it is a core service only. Int

Service Options

# With shell, you can just pass the correct header with each request
curl "/api/v1/service-options" \
  -XGET \
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "request_token": "uoG7vrxxxxxxxxxxxxxxxxxx" }'
<?php

$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ],
    'json' => [
        'request_token' => 'uoG7vrxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/service-options', $options);

import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = { 'request_token': 'uoG7vrxxxxxxxxxxxxxxxxxx' }

requests.get('/api/v1/service-options', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
     method: 'GET',
     headers: {
         'Accept': 'application/json',
         'Content-Type': 'application/json',
         'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
     }
 };

fetch('/api/v1/service-permissions', options)
 .then((response) => {
     return response.json();
 })
 .catch((error) => {
     console.log(error);
 })

If your request is valid, the above command returns JSON structured like this:

{
    "data": [
        {
            "id": 1,
            "name": "location",
            "description": "<p>Services can access and will receive the device location</p>",
            "core_only": 0
        },
        {
            "id": 2,
            "name": "push_requests",
            "description": "<p>This service is allowed to send self-defined push requests to the users device.</p>",
            "core_only": 0
        },
        {
            "id": 3,
            "name": "access_email",
            "description": "<p>This service is allowed to see users email address.</p>",
            "core_only": 0
        }
    ],
    "timestamp": "2019-07-06 11:08:00"
}

/api/v1/service-options GET

Most services, in some form or another, will need to persist user input values. While our policy remains to leave as much freedom to each service provider as possible, we still want to give users a clean and unified user experience. This is why we integrated the Service Options.

Service Options allow a service to define some basic input fields which the user can access through the settings menu in the app. As a service provider, you can add as many service option fields to your service as you want. For now, they need to stick to basic input values, such as checkboxes and text inputs. Check the corresponding endpoint to get a full list of available options.

You will receive those values with each user request (user_options). Additionally, you can access the user profile if you pass your service request_token accordingly as a query parameter when calling /api/v1/users/{userId}/services/{service} (GET request). At the time of creating, we support text areas, text input fields and checkboxes. When you add Service Options to your service, you need to pick which design the answer possibility for the user needs to be, based on the response of this endpoint.

If you have added some options to your service, the values per user can be manipulated in two ways. As mentioned, the user can access them through the settings menu in the Gigaaa app. Alternatively, you, as a service provider, can receive and change those values. To change them send a PUT request to /api/v1/users/{user]/services/{serviceId}, holding an array user_options with all values you want to change or add. You can only set values for which you have created a Service Option. Please make sure each options key is correctly named. By default we will use a snake_case version of your set label value (i.e. this_is_my_label_key).

Response

Parameter Description Type
id Unique option ID. Int
type Type of input. String
description Description of the option. String
validation_rule Rules for how the option input should be validated. String

Adding Service Options to a Service

To add options to the users service configuration, pass them when updating your service. Service options require a label and optionally allow you to add a help_text, next to the options id.

Get all Service Categories


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-categories"
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/service-categories', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/service-categories', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/service-categories", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "0": {
        "id": 6,
        "parent_id": null,
        "image_filename": null,
        "published": 1,
        "created_at": "2019-01-18 08:44:43",
        "updated_at": "2019-01-18 08:44:43",
        "translations": []
    },
    "1": {/* .. another Service Category */},
    "2": {/* .. another Service Category */},
    "timestamp": "2019-08-19 15:53:11"
}

/api/v1/service-categories GET

Response

Parameter Description Type
id Unique category ID. Int
parent_id Parent ID. Int
image_filename Filename of the category image. String
published Publication status of category. Int
translations Array with all translation objects. Array

Create new Service Categories


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-categories" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{
        "published": 1, 
        "translations": [ 
            [ 
                "title": "My Category", 
                "description": "My first Category", 
                "locale": "en_US" 
            ]
        ] 
     }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'json' => [
        'published'    => 1, 
        'translations' => [
            [
                'title'       => 'My Category', 
                'description' => 'My first Category', 
                'locale'      => 'en_US'
            ]
        ]
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/service-categories', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 
    'published': 1, 
    'translations': [
        [ 
            'title': 'My Category', 
            'description': 'My frist Category', 
            'locale': 'en_US' 
        ] 
    ] 
}  

requests.post('/api/v1/service-categories', data=json.dumps(payload), headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "published": 1, 
        "translations": {
            "title": "My Category", 
            "description": "My first Category", 
            "locale": "en_US"
        }
    })
};

fetch("/api/v1/service-categories", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "0": {
        "id": 6,
        "parent_id": null,
        "image_filename": null,
        "published": 1,
        "created_at": "2019-01-18 08:44:43",
        "updated_at": "2019-01-18 08:44:43",
        "translations": []
    },
    "1": {/* .. another Service Category */},
    "2": {/* .. another Service Category */},
    "timestamp": "2019-08-19 15:53:11"
}

/api/v1/service-categories POST

Adding, updating and removing service categories requires management rights for your user profile. All changes take effect immediately.

Request

Parameter Description Type Required
image Image for the Service Category. Image False
published Publication status of Service Category. Bool False
parent_id Parent ID. Int Null
translations Each service can be translated into multiple languages. Pass a nested array containing all the language fields. (title, description and locale) Array True, min. 1 translation

Response

Parameter Description Type
id Unique Service Category ID. Int
parent_id Parent ID. Int
image_filename Service Category image. String
published Publication status of Service Category Int
translations Array with all Translation Objects. Array

Get one Service Category


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-categories/36" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/service-categories/36', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/service-categories/36', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/service-categories/36", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 36,
    "parent_id": null,
    "image_filename": null,
    "published": 1,
    "created_at": "2019-03-21 13:26:14",
    "updated_at": "2019-03-21 13:26:14",
    "parent": null,
    "translations": [],
    "children": [],
    "timestamp": "2019-08-19 15:58:30"
}

/api/v1/service-categories/{serviceCategoryId} GET

The relations for the requested service category will automatically be added. Those include parent and child categories and translations.

Response

Parameter Description Type
id Unique service category ID. Int
parent_id Parent ID. Int
image_filename Filename of the category image. String
published Publication status of service category. Int
parent - Int
translations Array of all translation objects. Array
children Array with all children objects. Array

Update a service category


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-categories/6" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ 
        "title": "First Category", 
        "description": "First Category Description", 
        "published": "1" 
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'json' => [
        'title'         => 'First Category', 
        'description'   => 'First Category Description', 
        'published'     => 1
    ]     
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/service-categories/6', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 
    'title': 'First Category',
    'description': 'First Category Description',
    'published': 1
}

requests.put('/api/v1/service-categories/6', data=json.dumps(payload), headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "title": "First Category",
        "description": "First Category Description",
        "published": "1"
    })
};

fetch("/api/v1/service-categories/6", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "status": true,
    "timestamp": "2019-08-20 11:23:53"
}

/api/v1/service-categories/{serviceCategoryId} PUT

Request

Parameter Description Type Required
image Image for the Service Category. Image False
published Publication status of the Service Category. Int False
parent_id Parent ID. Int False
translations Each service can be translated into multiple languages. Pass a nested array containing all the language fields. (title,descriptionandlocale`) Array True, min. 1 translation

Response

Parameter Description Type
success True, if updating the Service Category was successful. Bool

Delete Service Category


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-categories/6" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ] 
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/service-categories/6', $options);


import requests

headers = {
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/service-categories/6', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/service-categories/6", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "status": true,
    "timestamp": "2019-08-20 11:23:53"
}

/api/v1/service-categories/{serviceCategoryId} DELETE

Response

Parameter Description Type
success True, if deleting the Service Category was successful. Bool

Service Images

Each Service can have one or more images. For an image to show, it must be published (published = 1) and not blocked (block = 0).

Create new service image


# With shell, you can just pass the correct header with each request

curl "/api/v1/services/218/images" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -F 'service_image=@path/to/file/image.jpg'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'multipart' => [
        'name'     => 'image.jpeg',
        'contents' => fopen('path/to/file/image.jpg'), 
        'headers'  => [
            'Content-Type'        => 'image/jpeg', 
            'Content-Disposition' => 'form-data; name="service_image" filename="image.jpeg"'
        ]
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/services/218/images', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

files = { 'image': open('path/to/file/image.jpg', 'rb') }

requests.post('/api/v1/services/218/images', files=files, headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer mXa7NGk9arxxxxxxxxxxxxxxxxxxx'
    }, 
    body: new FormData().append('file', input.files[0])
};

fetch('/api/v1/services/218/images', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "uuid": "2a71b22f-e8ed-4eca-b93d-7ded410e3005",
    "published": 1,
    "order": "1",
    "gigaaa_service_id": 218,
    "updated_at": "2019-08-19 16:11:44",
    "created_at": "2019-08-19 16:11:44",
    "url": "https://mp2.gigaaa.link/api/v1/service-images/2a71b22f-e8ed-4eca-b93d-7ded410e3005",
    "timestamp": "2019-08-19 16:11:44"
}

/api/v1/services/{serviceId}/images

Request

Parameter Description Type Required
image Image for your service. Image/File True
order Defines the order if multiple images are present. (Default = last) Int False
published Value decides if the image is published. Int False

Response

Parameter Description Type
uuid UUID of the service image. String
published Publication status of the service image. Int
order Position of the image, if the service has multiple images. String
gigaaa_service_id Unique Gigaaa Service ID. Int
url URL to the service image. URL

If everything worked fine, you will receive the created image object in the response together with the public image url.

Each image will be automatically converted into different sizes. At this moment, we have the following sizes. The resolutions will most likely change soon, while the names remain.

Size Resolution
micro 30x30
tiny 120x120
preview 300x300
small 400x400
default 1024x1024

Get all service images


# With shell, you can just pass the correct header with each request

curl "/api/v1/services/218/images" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer xP9kl1nxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-type'  => 'application/json', 
        'Authorization' => 'xP9kl1nxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/services/218/images', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/services/218/images', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/services/218/images', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "0": {
        "uuid": "2a71b22f-e8ed-4eca-b93d-7ded410e3005",
        "gigaaa_service_id": 218,
        "order": 1,
        "block": 0,
        "published": 1,
        "created_at": "2019-08-19 16:11:44",
        "updated_at": "2019-08-19 16:11:44",
        "url": "https://mp2.gigaaa.link/api/v1/service-images/2a71b22f-e8ed-4eca-b93d-7ded410e3005"
    },
    "1": {/* .. another Service Image */},
    "2": {/* .. another Service Image */},
    "timestamp": "2019-08-19 16:19:05"
}

/api/v1/services/{serviceId}/images GET

Response

Parameter Description Type
uuid UUID of the service image. String
published Publication status of the service image. Int
order Position of the image, if the service has multiple images. String
gigaaa_service_id Unique Gigaaa Service ID. Int
url URL to the service image. URL

Get a specific service image


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-images/adef149d-1da6-4597-bdd3-6ab31586e432?size=tiny" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: xP9kl1nxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-type'  => 'application/json', 
        'Authorization' => 'xP9kl1nxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/service-images/adef149d-1da6-4597-bdd3-6ab31586e432?size=tiny', $options);


import requests

headers = { 
    'Accept': 'application/json',
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/service-images/adef149d-1da6-4597-bdd3-6ab31586e432?size=tiny', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/service-images/adef149d-1da6-4597-bdd3-6ab31586e432?size=tiny', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

The response will be the image file.

/api/v1/service-images/{uuid}?size GET

Service images are generally public and accessibly by anyone who is logged in.

Parameter Description Type Required
size If you want to get your image in a specific size, you can add the size parameter to the public url, i. e /api/v1/service-images/{uuid}?size. String False

Response

The response will be the image file.

Update a service image


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-images/c7a5f898-2d33-4794-90a0-173688005f0a" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: xP9kl1nxxxxxxxxxxxxxxx' \
  -d '{ 
         "published": 0, 
         "order": 22 
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-type'  => 'application/json', 
        'Authorization' => 'xP9kl1nxxxxxxxxxxxxxxxx'
    ], 
    'json' => [
        'published' => 0, 
        'order'     => 22
    ]           
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/service-images/c7a5f898-2d33-4794-90a0-173688005f0a', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = { 
    'published' : 0,
    'order': 22 
}

requests.put('/api/v1/service-images/c7a5f898-2d33-4794-90a0-173688005f0a', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'PUT',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    }, 
    body: JSON.stringify({
        'published': 0, 
        'order': 22
    })
};

fetch('/api/v1/service-images/c7a5f898-2d33-4794-90a0-173688005f0a', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-19 16:35:40"
}

/api/v1/service-images/{uuid} PUT

Parameter Description Type Required
published Defines if the image is published. Int False
order Defines the order if multiple images are present. (Default = last) Int False

Response

Parameter Description Type
success True, if service image was successfully updated. Bool

Delete a service image


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-images/c7a5f898-2d33-4794-90a0-173688005f0a" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer xP9kl1nxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-type'  => 'application/json', 
        'Authorization' => 'xP9kl1nxxxxxxxxxxxxxxxx'
    ]       
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/service-images/c7a5f898-2d33-4794-90a0-173688005f0a', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/service-images/c7a5f898-2d33-4794-90a0-173688005f0a', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'DELETE',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/service-images/c7a5f898-2d33-4794-90a0-173688005f0a', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-19 16:39:45"
}

/api/v1/service-images/{uuid} DELETE

Response

Parameter Description Type
success True, if service image was deleted successfully. Bool

Service endpoint

Please pay special attention to your communication endpoint. See Service Communication for further details.

Health Status Indicators

Our system is checking each service's health at several points. Foremost, every few hours based on our regular routine. We also track response times during user requests. If we try to contact your service and it fails, we add the reason for deactivation as described in the table below to the service while the deactivation process occurs. If your service gets deactivated, you must restore adherence to the strict activation rules to get the service reactivated and make it accessible for users again.

Constant Code Description
GIGAAA_SERVICE_STATUS_ALL_GOOD 0 Service is in perfect condition.
GIGAAA_SERVICE_STATUS_ENDPOINT_ERROR 1 Service is returning an error.
GIGAAA_SERVICE_STATUS_NO_RESPONSE 2 Service is not responding at all.
GIGAAA_SERVICE_STATUS_TIMEOUT 3 Service exceeded the maximum response time.
GIGAAA_SERVICE_STATUS_LEGAL_VIOLATION 4 Service violated the legal terms.
GIGAAA_SERVICE_STATUS_TOO_MANY_COMPLAINTS 5 Service has received too many complaints.
GIGAAA_SERVICE_STATUS_FRAUD_SUSPECT 6 Service is suspected to be fraudulent.
GIGAAA_SERVICE_STATUS_TOO_AGGRESSIVE_LANGUAGE_CAPTURE 7 Service used trigger sentences that are too generic.
GIGAAA_SERVICE_SENTENCE_ENDPOINT_ERROR 8 Service has an endpoint error.
GIGAAA_SERVICE_SENTENCE_VALIDATION_FAILED 9 Trigger sentences of service failed the validation.
GIGAAA_SERVICE_UNKNOWN_ERROR 10 Service has an unknown error.

Interaction between Gigaaa, Gigaaa User and Your Service

Please see Service Communication.

Possible In-App Actions

Please see In-App Actions.

NLU

Trigger Sentences

Trigger sentences are essential when building a service. Since we don't have a "keyboard and mouse" way of opening a service, trigger sentences are of special importance. They define how a user can activate a service.

Put yourself in the position of a user. A typical user will use dozens of different services each day. He wants to easily access all of them.

If your trigger sentences don't match the natural user behavior for that particular use case, it will quickly feel unnatural. That means your service is not going to be used as much as it could be. On the other hand, if you define a range of sentences/words that is too wide, users may get annoyed since your service might keep getting triggered in situations where the user meant to invoke some other service.

Don't be too aggressive when you define your trigger sentences. But, on the other side, that doesn't mean that you should minimize your trigger sentences at all costs. You should add enough variations and different ways for the user to express themselves. As long as it is not crossing the boundary of interference with other intents. Always try to think of precise ways for how users will be able to trigger your service.

Keep in mind that you don't need to publish all trigger sentences which correspond to your service. We only need ->trigger<- sentences, which kick off your service and forward the initial user request. If you expect a secondary response or follow up questions, you set the expect_reply to true on your service response. You can read more about conversations with more than one question/answer sequence.

If you just want to deploy your sentences, check out Trigger Sentences Deployment

Special Note on NLU

If you decide to use our NLU and filter entities, make sure you provide enough variations of your sentences. The quality will dramatically depend on it. If you want to keep things simple, take a look on how to pass additional metadata with static trigger sentences.

Service Deployment

Once you have created your service and it is running smoothly in your local environment, you are at the point where you will likely want to make it accessible to our Gigaaa community. This chapter will guide you through that process.

Please make sure you have read and understood everything about Gigaaa services from the previous chapters. You also should keep in mind our available endpoints.

Implement Your First Service

All services must be added to our global services stack. But don't worry, compared to the service development, adding a service is a significantly easier task.

In short, it can be done by sending a POST request to /api/v1/services holding all the required fields for a service. Please see the response whether it was successful or not. If so, it will contain your service id. You will also find the request_token which will allow you to send asynchronous requests and catch service-related information and user options later on. MAKE SURE YOU COPY THAT VALUE AND STORE IT IN A SAFE LOCATION!

At a minimum, you need to pass a title and your endpoint. But to have your service published and accessible, you also need to define at least one country, one language, one trigger sentence for that language, and set the service to publish.

Check out all available options here and here.

Usually, if all data is provided, your service will be available right away for our users. But, in certain cases, it can take up to 12 hours.

Don't forget to authenticate your requests or you will get a 401 Permission denied response. When you authenticate yourself, your user_id will always be added to this service's usersOrganizingThisService with admin privileges.

Publish Trigger Sentences

When you pass a language you support, please pay attention to our languages endpoint. Only languages with language_file = 1 are valid. Trigger sentences passed by internal services using the API will be ignored. For that, you need an additional access to our "Sentence database". Please contact us to get separated credentials and access.

There are two primary ways to add sentences to your (core) service.

  1. When you POST your service simply add a json_string with your sentences.
  2. Make the sentences available under your endpoint so our system crawls them automatically on a regular basis.

Sentences can come in one of three different formats:
- A plain text string. My trigger sentence 2
- A text string with tagged entities. Our NLU will try to recognize their values and pass them to your endpoint. I want to buy <product>Tomatos</product>.
- A structured array, holding extra meta information.

[
    "sentence" => "My trigger sentence 1.",
    "entities" => [
        "entity" => "value",
        "product"  => "tomatos"
    ]
];

Note: All sentences must conform to the same format.

You can add additional values, such as an intent, which will get passed to your service along the requests or negative_trigger_sentences, which prevent specific terms from triggering your service.

Since you will most likely need more than one sentence, you have to nest them inside a parent array. Each child holds a language_id.

[
       [
           'language_code'              => 'en',
           'trigger_sentences'          => [
               [
                   'sentence' => 'I want to buy a Tomato',
                   'intent'   => 'my_intent', // Optional, will be auto generated if not passed
                   'entities' => [ // Optional
                       'entity'  => 'value',
                       'product' => 'Tomato'
                   ]
               ], // ... more trigger sentences
           ],
           'negative_trigger_sentences' => [ // Optional
               [
                   'sentence' => 'sentence'
               ]
           ],
       ], // ... more languages
   ];

Service Store

The Service Store is a directory containing all services which have been added to gigaaa, either by external developers or the gigaaa core team.

The service store follow a handful of concepts. Remember: at its core, gigaaa is a network of services. It always needs a service to handle and process a request, after it identified the users intent. Some services are declared as "Core Services" and are active by default. But most services needs to get manually picked by the user, to be eligible to process an intent.

The service store also provides information about special permission a services needs, to process a request.

Get all services


# With shell, you can just pass the correct header with each request

curl "/api/v1/services" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/services', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/services', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/services", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "intent": "Weather Service",
            "published": 1,
            "core_service": 0,
            "status": 1,
            "auto_translate": 0,
            "block": 0,
            "added_to_current_user_stack": false,
            "short_description": "",
            "countries": [/* Array with Countries */],
            "permissions": [/* Array with Service Permissions */],
            "options": [/* Array with Service Options */)],
            "translations":  [
                {
                  "id": 4,
                  "title": "Weather Service",
                  "description": null,
                  "gigaaa_service_id": 1,
                  "locale": "en"
                }
            ]
        }
    ],
    "first_page_url": "https://mp2.gigaaa.link/api/v1/services?page=1",
    "from": 1,
    "last_page": 2,
    "last_page_url": "https://mp2.gigaaa.link/api/v1/services?page=2",
    "next_page_url": "https://mp2.gigaaa.link/api/v1/services?page=2",
    "path": "https://mp2.gigaaa.link/api/v1/services",
    "per_page": 3,
    "prev_page_url": null,
    "to": 3,
    "total": 6,
    "timestamp": "2019-08-19 16:59:11"
}

/api/v1/services GET

You can find services using our index endpoint. You will be able to list all published services, filter your results using the following parameters and paginate through the results. For now, we support two types of filter. If you want to filter all services based on their category affiliation, you can add one or more category ids to the service index request (/api/v1/services?categories[]=:serviceId).

Request

Parameter Description Type Required
title Can be used to filter service title. (All title translations will be included in this search.) String False
categories You can restrict services by categories. Pass an array with all category ids you wish to find. Array False
categories.*id Category ID. Int False
per_page Define how many results you would like to see per page. Int, min: 1, max. 100 False
page The page you would want to display. Int False

Response

Note: The response will always be paginated. The data property in the response will contain the services.

Parameter Description Type
id Unique service ID. Int
intent Intent of the service. String
published Publication status of the service. Int
core_service Determines, if the service is a core service. Int
status Health status of the service. Int
auto_translate If you add more "languages" than you offer trigger_sentences for, you can choose to let our system automatically translate the missing ones. Int
block Determines, if the resource is blocked. Int
added_to_current_user_stack Determines, whether the service is in the current users service stack. Bool
short_description Short description of the service. String
countries Array of countries. Array
permissions Array of permissions. Array
options Array of options. Array
translations Array of translations. Array

Get all user services


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2521/services" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "include_services_user_organizes": true }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'json' => [
        'include_services_user_organizes' => true
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2521/services', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'include_services_user_organizes': true }

requests.get('/api/v1/users/2521/services', data=json.dumps(payload), headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "include_services_user_organizes": true
    })
};  

fetch("/api/v1/users/2521/services", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:


{
    "services": [
        {
            "id": 216,
            "title": "Weather Service",
            "description": "",
            "intent": "",
            "endpoint": "https://www.weatherservice.com",
            "trigger_sentences": [],
            "trigger_sentences_hash": null,
            "priority": 0,
            "published": 0,
            "core_service": 0,
            "status": 0,
            "health_check_at": null,
            "added_to_current_user_stack": false,
            "short_description": "",
            "countries": [],
            "permissions": [],
            "options": [],
            "languages": [],
            "categories": [],
            "users_organizing_this_service": []
        },
        {/* .. another Service */}
    ],
    "include_services_user_organizes": [
        {
            "id": 216,
            "title": "Weather Service",
            "published": 0,
            "is_questionnaire_service": false
        },
        {/* .. another Service */}
    ],
    "timestamp": "2019-08-20 09:01:11"
}

/api/v1/users/{userId}/services GET

Request

Parameter Description Type Required
include_services_user_organizes If true, Services which are organized by the user will be included in the response. Bool False

Response

Parameter Description Type
services Array with all user services. Array
include_services_user_organizes Array with all services the user organizes. Array

Add a service to a User Service Stack


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2521/services/1" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/2521/services/1', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.post('/api/v1/users/2521/services/1', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};  

fetch("/api/v1/users/2521/services/1", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "status": {
        "attached": [
            1
        ],
        "detached": [],
        "updated": []
    },
    "timestamp": "2019-08-20 09:41:00"
}

/api/v1/users/{userId}/services/{serviceId} POST

Response

Parameter Description Type
status Status Object Object
status.*.attached Array with service IDs that got added to the user stack. Array
status.*.detached Array with service IDs that got removed from the user stack. Array
status.*.updated Array with service IDs that got updated. Array

Get service relation details


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2521/services/3" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2521/services/3', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2521/services/3', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};  

fetch("/api/v1/users/2521/services/3", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "exists": true,
    "is_core_service": 0,
    "user": {
        "email": "peter@tenmedia.de"
    },
    "user_options": null,
    "timestamp": "2019-08-20 09:49:31"
}

/api/v1/users/{userId}/services/{serviceId} GET

This endpoint is open for both, the user and the service itself. It contains information about the relationship. For example, if a service requires a users email address to operate, it is added to this response. Same goes for all other suitable values. Also added are user options the user has set.

Response

Parameter Description Type
exists True, if the service is in the users service stack. Bool
is_core_service Determines, whether the service is a core service. Int
user Object that contains every property the service requires from the user to operate. Object
user_options Array with user options. Array

Update a services user options

# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2521/services/1" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ 
         "user_options": { 
              "service_option_input_name": "value", 
              "favorite_film": "Bugs Bunny", 
              "introduction": "Lorem Ipsum Lorem Ipsum", 
              "use_default_values": true 
         } 
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'json' => [

    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/users/2521/services/1', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 
    "user_options" => [ 
        "service_option_input_name" => "value", 
        "favorite_film"             => "Bugs Bunny", 
        "introduction"              => "Lorem Ipsum Lorem Ipsum", 
        "use_default_values"        => true 
    ] 
}

requests.put('/api/v1/users/2521/services/1', data=json.dumps(payload), headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }, 
    body: JSON.stringify({
        "user_options": {
            "service_option_input_name": "value",
            "favorite_film": "Bugs Bunny",
            "introduction": "Lorem Ipsum Lorem Ipsum",
            "use_default_values": true
        }
    })
};  

fetch("/api/v1/users/2521/services/1", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-29 13:18:39"
}

/api/v1/users/{userId}/services/{serviceId} PUT

When updating user option, you need to pass an array of options which the service supports. You cannot just pass any values, they must explicitly be added by the service.

Passed options which don't belong to an existing Service Option will be ignored.

Request

Parameter Description Type Required
user_options Edit the user options. Array False

Response

Parameter Description Type
success True, if updating the user options was successful. Bool

Remove a service from a User Service Stack


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2521/services/1" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/users/2521/services/1', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/users/2521/services/1', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};  

fetch("/api/v1/users/2521/services/1", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "status": true,
    "timestamp": "2019-08-20 10:18:39"
}

/api/v1/users/{userId}/services/{serviceId} DELETE

Response

Parameter Description Type
success True, if service was successfully delete from the user stack. Bool

Service Environments

A Service Environment is a closed off environment where users can specify which services are able to be triggered during a request to our Gigaaa Conversation endpoint (/api/v1/gigaaa-conversations). After you have created a Service Environment, you will receive a UUID which you can then pass as an attribute (service_environment_uuid) when contacting our endpoint.

Service environments are managed by users. Users can have manger permissions (2), which allows to update the permission or admin permissions (3), which additionally allows deleting the environment. The user creating an environment will automatically be added as an admin user.

Get all Service Environments


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-environments" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/service-environments', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/service-environments', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/service-environments", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:


[
    {
        "uuid": "376j0ap-a56c-7560-af18-e32ab35tb2n8",
        "title": "Sandbox Environment",
        "description": "Testing some services.",
        "created_at": "2019-10-01 10:49:07",
        "updated_at": "2019-10-01 10:49:07",
    }, 
    {/* .. another Service Environment */}
]

/api/v1/service-environments GET

Request

Parameter Description Type Required
user_id The user of whom the environments should be returned. Default value is current user id for non-developers. int false

Response

Parameter Description Type
uuid UUID of the Service Environment String
title Title of the Service Environment String
description Description of the Service Environment String

Create a Service Environment


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-environments" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{
          "title": "Sandbox Environment",
          "users": [
              {
                  "id": 1, 
                  "permissions": 3
              }
          ], 
          "services": [
              1, 5, 3
          ]
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
          'title' => 'Sandbox Environment',
          'users' => [
              [
                  'id' => 1, 
                  'permissions' => 3
              ]
          ], 
          'services' => [
               1, 5, 3
          ]
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/service-environments', $options);


import json
import requests

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = {
    'title': 'Sandbox Environment',
    'users': [
        {
            'id': 1, 
            'permissions': 3
        }
    ], 
    'services': [
        1, 5, 3
    ]
}

requests.post('/api/v1/service-environments', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "title": "Sandbox Environment",
        "users": [
            {
                "id": 1, 
                "permissions": 3
            }
        ], 
        "services": [
            1, 5, 3
        ]
    })
};

fetch("/api/v1/service-environments", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "uuid": "376j0ap-a56c-7560-af18-e32ab35tb2n8",
    "title": "Sandbox Environment",
    "description": "Testing some services.",
    "created_at": "2019-10-01 10:49:07",
    "updated_at": "2019-10-01 10:49:07"
}

/api/v1/service-environments POST

Request

Parameter Description Type Required
title Title of the Service Environment String True
description Description of the Service Environment String False
users Array with all User Arrays. Array False
users.* Array containing the user ID and the permission level of the user. Int False
users.*.id Unique User ID. Int False
users.*.permission Permission level of the user. Int False
services Array with all Service Arrays. Array False
services.*.id Unique Service ID. Int true
services.*.priority Priority of this service. If multiple services are matching, the one with the highest priority will be prefered to handle the request. The priority can be between 0 and 99. Default is 50. Int False

Response

Parameter Description Type
uuid UUID of the Service Environment String
title Title of the Service Environment String
description Description of the Service Environment String

Get a Service Environment


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-environments/4" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/service-environments/4', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/service-environments/4', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/service-environments/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "uuid": "536d7fba-ebaf-4a7b-8312-d36204cf67ae",
    "title": "Sandbox Environment",
    "description": "intent",
    "created_at": "2019-10-01 16:08:13",
    "updated_at": "2019-10-01 16:08:13"
}

/api/v1/service-environments/{serviceEnvironmentUuid} GET

Response

Parameter Description Type
uuid UUID of the Service Environment String
title Title of the Service Environment String
description Description of the Service Environment String
services Nested Array with IDs and priorities of all added services Array

Update a Service Environment


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-environments/4" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "title": "Sandbox Environment - Two" }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'title' => 'Sandbox Environment - Two',
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/service-environments/4', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'title': 'Sandbox Environment - Two' }

requests.put('/api/v1/service-environments/4', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "title": "Sandbox Environment - Two",
    })
};

fetch("/api/v1/service-environments/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your update process was successful, your will get a confirmation like that:

{
    "status": true,
    "timestamp": "2019-09-30 14:37:14"
}

/api/v1/service-environments/{serviceEnvironmentId} PUT

Response

Parameter Description Type
success True, if Service Environment was successfully updated. Bool

Delete a Service Environment


# With shell, you can just pass the correct header with each request

curl "/api/v1/service-environments/4" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/service-environments/4', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/service-environments/4', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/service-environments/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "status": true,
    "timestamp": "2019-09-30 16:51:59"
}

/api/v1/service-environments/{serviceEnvironmentId} DELETE

Response

Parameter Description Type
success True, if Service Environment was successfully deleted. Bool

Users

Create a new user


# With shell, you can just pass the correct header with each request

curl "/api/v1/auth/signup" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -d '{ 
        "username": "John Doe" 
        "email": "John@Doe.com" 
        "password": "password" 
      }'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ],
    'json' => [
        'username'  => 'John Doe', 
        'email'     => 'John@Doe.com', 
        'password'  => 'password'
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/auth/signup', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json' 
}

payload = { 
    'username': 'John Doe', 
    'email': 'John@Doe.com',
    'password': 'password' 
}

requests.post('/api/v1/auth/signup', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        'username': 'John Doe', 
        'email': 'John@Doe.com', 
        'password': 'password'
    })
};

fetch('/api/v1/auth/signup', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-16 16:56:36"
}

/api/v1/auth/signup POST

Right now, users can only be created using the regular signup process.

After the signup the user will receive an email with a link to verify his account. Without said verification the user will have limited access to our application.

Request

Parameter Description Type Required
name Username String True
email Email Email True
password Password String True

Response

Parameter Description Type
success Returns true, if signup was successful. Bool

Resend Email Verification


# With shell, you can just pass the correct header with each request

curl "/email/resend" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/email/resend', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json' 
}

requests.get('/email/resend', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
};

fetch('/email/resend', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-16 16:56:36"
}

/email/resend GET

This route will resend the verification email for the currently logged in user.

Response

Parameter Description Type
success Returns true, if sending the verification email was successful. Bool

Get currently authenticated user


# With shell, you can just pass the correct header with each request

curl "/api/v1/current-user" \
  -XGET \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/current-user', $options);


import requests

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

requests.get('/api/v1/current-user', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/current-user', options)
    .then((response) => {
       return response.json();
    })
    .catch((error) => {
       console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
  "id": 2521,
  "name": "Jane",
  "email": "jane@doe.com",
  "language_id": 83,
  "api_token": "6urUK43TvXwKrxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "block": 0,
  "created_at": "2019-08-15 17:25:31",
  "avatar_url": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback",
  "avatar_url_tiny": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback?size=tiny",
  "is_tester": false,
  "language": {/* Language Object */},
  "profile": {/* Profile Object */},
  "timestamp": "2019-08-19 11:57:06"
}

/api/v1/current-user GET

Request

Parameter Description Type Required
load_user_profile If set true, the entire user profile will be loaded. Otherwise only the user object is returned. Bool False
load_service_stack If true, all services this users has are added. Bool False

Response

Parameter Description Type
success True, if request was successful. Bool
id Unique User ID. Int
name Username String
email User email String
language_id Language ID of user. Int
api_token API Token for authorization. String
block Determines, if the resource is blocked. Int
created_at Creation date of user. Date String
avatar_url URL to user image. URL
avatar_url_tiny URL to user image. (Returns smallest image size.) URL
is_tester Determines, whether the user is a tester. Bool
is_saved_user Determines, whether the user is a saved by another user. Bool
is_contact Determines, whether the user is a contact of another user. Bool
full_name Full name of the user. String
display_name Display name of the user. String
external_profile Determines, whether the user has an external profile. Bool
unread_notification_counts Object with inherent Notification properties. Object
contacts Array of all user contacts. Array
language Language Object with all language properties. Object
profile Object with all profile information. Object
unread_notification Array of all unread notifications Array
conversations Object with all conversations properties. Object
open_contact_requests_received Array of open contact requests. Array
contacts_received Array with User IDs that the current user received. Array
contacts_sent Array with User IDs that the current user sent. Array

Get user notifications


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/notifications" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer xP9kl1nxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-type'  => 'application/json', 
        'Authorization' => 'xP9kl1nxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/notifications', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/notifications', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/notifications', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:


/api/v1/users/notifications GET

Request

Parameter Description Type Required
mark_as_read If set true, all loaded messages will marked as read. Bool False

Response

Parameter Description Type

Send a user notification


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/notifications" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer xP9kl1nxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-type'  => 'application/json', 
        'Authorization' => 'xP9kl1nxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/notifications', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.post('/api/v1/users/notifications', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/notifications', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:


/api/v1/users/notifications POST

Request

Parameter Description Type Required
notifications - Array True
notifications.*.channels - Array True
notifications.*.channels.* - ? ?
notifications.*.user_id - Int True
notifications.*.data - Array True
notifications.*.data.icon - String False
notifications.*.data.message - String True
notifications.*.data.url - String False
notifications.*.mail - Array True, if notifications.*.channels.mail is given.
notifications.*.mail.line_one - String True, if notifications.*.mail is given.
notifications.*.mail.line_two - String True, if notifications.*.mail is given.
notifications.*.mail.action - String True, if notifications.*.mail is given.
notifications.*.broadcast_on - String True, if notifications.*.channels.websocket is given.
notifications.*.broadcast_as - String True, if notifications.*.broadcast_on is given.
notifications.*.broadcast_type - ? False
notifications.*.push_notification_title - String True, if notifications.*.push is given.
notifications.*.push_notification_message - String True, if notifications.*.push is given.

Response

Parameter Description Type

Upload avatar


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/avatar" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -F 'avatar=@path/to/file/avatar.jpg'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'multipart' => [
        'name'     => 'avatar.jpeg',
        'contents' => fopen('path/to/file/avatar.jpg'), 
        'headers'  => [
            'Content-Type'        => 'image/jpeg', 
            'Content-Disposition' => 'form-data; name="avatar" filename="avatar.jpeg"'
        ]
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/2/avatar', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

files = { 'image': open('path/to/file/avatar.jpg', 'rb') }

requests.post('/api/v1/users/2/avatar', files=files, headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer mXa7NGk9arxxxxxxxxxxxxxxxxxxx'
    }, 
    body: new FormData().append('file', input.files[0])
};

fetch('/api/v1/users/2/avatar', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-16 17:26:33"
}

/api/v1/users/{userId}/avatar POST

Request

Parameter Description Type Required
avatar Your profile image. Image file True

Response

Parameter Description Type
success True, if avatar was successfully added. Bool

Get all users


# With shell, you can just pass the correct header with each request

curl "/api/v1/users" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer xP9kl1nxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-type'  => 'application/json', 
        'Authorization' => 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "name": "John Doe",
            "language_id": 83,
            "block": 0,
            "created_at": "2017-12-21 16:32:00",
            "avatar_url": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback",
            "avatar_url_tiny": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback?size=tiny",
            "is_tester": false,
            "profile": {
                "gender": 0,
                "title": null,
                "first_name": "John",
                "last_name": "Doe",
                "about_me": null,
                "home_port": null,
                "image": null,
                "birthday": null
            }
        }
    ],
    "first_page_url": "https://mp2.gigaaa.link/api/v1/users?page=1",
    "from": 1,
    "last_page": 117,
    "last_page_url": "https://mp2.gigaaa.link/api/v1/users?page=117",
    "next_page_url": "https://mp2.gigaaa.link/api/v1/users?page=2",
    "path": "https://mp2.gigaaa.link/api/v1/users",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 2331,
    "timestamp": "2019-08-16 17:08:47"
}

/api/v1/users GET

Request

Parameter Description Type Required
user_ids List of user ids to restrict the search results. Array False
user_ids.* Unique user ID. Int False
except_user_ids List of user ids which should be excluded from the search results. Array False
except_user_ids.* Unique user ID. Int False
filter Free text to filter the results. String False
mode You have different filter modes. If passed find_friends, only users which are not already befriended with the requesting user will be shown. If mode = except myself, the currently requesting user will be excluded. String False
per_page Limits the amount of users that are shown on a single page. Int False
order_by String that indicates the order of the users list. String (id or name) False
order_dir String that indicates the direction in which the users are listed. String (ASCor DESC) False

Response

Parameter Description Type
id Unique user ID. Int
name Name of the user. String
language_id Unique language ID of the language the user speaks. Int
block Determines, if the resource is blocked. Int
created_at Timestamp of creation date. String
avatar_url Link to the avatar of the user. URL
avatar_url_tiny Link to the small version of the avatar. URL
is_tester Determines, whether the user is a tester. Bool
profile.*.gender Gender of the user. Int
profile.*.title Title of the user. String
profile.*.first_name First name of the user. String
profile.*.last_name Last name of the user. String
profile.*.about_me About me description of the user. String
profile.*.home_port Home port of the user. String
profile.*.interests Comma-seperated list of the users interests. String
profile.*.image Avatar of the user. String
profile.*.birthday Birth date of the user. String

Get one user


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
    }
};

fetch('/api/v1/users/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 2521,
    "name": "John Doe",
    "language_id": 83,
    "block": 0,
    "created_at": "2019-08-15 17:25:31",
    "avatar_url": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback",
    "avatar_url_tiny": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback?size=tiny",
    "is_tester": false,
    "is_saved_user": false,
    "is_contact": false,
    "contact_request_received": false,
    "contact_request_sent": true,
    "full_name": "",
    "display_name": "John Doe",
    "external_profile": true,
    "is_blocked_by_current_user": false,
    "has_blocked_current_user": false,
    "current_user_can_report_this_user": true,
    "current_user_can_block_this_user": true,
    "saved_by_users": [/* User Objects */],
    "profile": null,
    "timestamp": "2019-08-16 17:20:23"
}

/api/v1/users/{userId} GET

Response

Note: The Response includes every parameter.

Parameter Description Type
id Unique user ID. Int
name Name of the user. String
language_id Unique language ID of the language the user speaks. Int
block Determines, if the resource is blocked. Int
created_at Timestamp of creation date. String
avatar_url Link to the avatar of the user. URL
avatar_url_tiny Link to the small version of the avatar. URL
is_tester Determines, whether the user is a tester. Bool
is_saved_user Determines, whether the user is a saved by another user. Bool
is_contact Determines, whether the user is a contact of another user. Bool
contact_request_received True, if the requested user received a contact request from the current user. Bool
contact_request_sent True, if the current user sent a contact request to the requested user. Bool
full_name Full name of the user. String
display_name Display name of the user. String
external_profile Determines, whether the user has an external profile. Bool
is_blocked_by_current_user True, if user is blocked by current user. Bool
has_blocked_current_user True, if user has blocked the current user. Bool
current_user_can_report_this_user Determines, whether the current user can report the user. Bool
current_user_can_block_this_user Determines, whether the current user can block the user. Bool
saved_by_users Array of saved users. Array
profile.*.gender Gender of the user. Int
profile.*.title Title of the user. String
profile.*.first_name First name of the user. String
profile.*.last_name Last name of the user. String
profile.*.about_me About me description of the user. String
profile.*.home_port Home port of the user. String
profile.*.interests Comma-seperated list of the users interests. String
profile.*.image Avatar of the user. String
profile.*.birthday Birth date of the user. String

Update a user


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "email": "John2@Doe2.com" }'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ], 
    'json' => [
        'email' => 'John2@Doe2.com'    
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/users/2}', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = { 'email': 'John2@Doe2.com' }

requests.put('/api/v1/users/2', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'PUT',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer mXa7NGk9arxxxxxxxxxxxxxxxxxxx'
    }, 
    body: JSON.stringify({ 'email': 'John2@Doe2.com' })
};

fetch('/api/v1/users/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-16 17:26:33"
}

/api/v1/users/{userId} PUT

Note: If the user has no profile yet and you pass profile parameters, the user profile will be created.

Request

Parameter Description Type Required
email Email Email False
name Username String False
language_id To set the default language for a user, you can either pass the language id from our language endpoint or the language_code itself. Int False
language_code See language_id. String False
password To change the password, send a new one here. String False
password_old If the user sends a new password, add the old one here for confirmation. String False
profile.gender Gender based on ISO 5218 (0 = not known, 1 = male, 2 = female, 9 = not applicable) Int False
profile.title Title of the user. String False
profile.first_name First name of user. String False
profile.last_name Last name of user. String False
profile.about_me "About me" description of user. String False
profile.home_port Home port of the user. String False
profile.interests Comma-seperated list of the users interests. String False
profile.birthday Birthday of user. Date False
profile.tutorial_seen Indicator whether or not the tutorial has been seen. Bool False
profile.onboarding_seen Indicator whether or not the onboarding screen should appear inside the app. Bool

Response

Parameter Description Type
success True, if user was successfully updated. Bool

Delete a user


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/users/2', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/users/2', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'DELETE',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-16 17:26:33"
}

/api/v1/users/{userId} DELETE

Response

Parameter Description Type
success True, if user was successfully deleted. Bool

See all Groups


# With shell, you can just pass the correct header with each request

curl "/api/v1/groups" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/groups', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/groups', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9arxxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/groups', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "0": {
        "id": 6,
        "name": "user",
        "description": null,
        "is_default": 1,
        "is_selectable": 1
    },
    "timestamp": "2019-08-16 17:31:42"
}

/api/v1/groups GET

Response

Parameter Description Type
id Unique group ID. Int
name Group name. String
description Description of the group. String
is_default Determines, whether this group is a default user group. Int
is_selectable Determines, whether a user can be added to this group. Int

See all groups a user is part of


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/groups" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/groups', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/groups', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/groups', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "0": {
        "id": 6,
        "name": "user",
        "description": null,
        "is_default": 1,
        "is_selectable": 1,
        "pivot": {
            "user_id": 2521,
            "group_id": 6,
            "created_at": "2019-08-19 12:27:03",
            "updated_at": "2019-08-19 12:27:03"
        }
    },
    "timestamp": "2019-08-19 12:27:34"
}

/api/v1/users/{userId}/groups GET

Response

Parameter Description Type
group Object with group properties. Object
group.*.id Unique group ID. Int
group.*.name Group name. String
group.*.description Description of the group. String
is_default Determines, whether this group is a default user group. Int
is_selectable Determines, whether a user can be added to this group. Int
pivot Object with pivot table information. Object

Add user to a group


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/groups" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer xP9kl1nxxxxxxxxxxxxxxx' \
  -d '{ "group_id": 6 }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-type'  => 'application/json', 
        'Authorization' => 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    ], 
    'json' => [
        'group_id' => 6
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/2/groups', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'group_id' : 6 }

requests.post('/api/v1/users/2/groups', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    }, 
    body: JSON.stringify({ 'group_id': 6 })
};

fetch('/api/v1/users/2/groups', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "attached": [
        6
    ],
    "detached": [],
    "updated": [],
    "timestamp": "2019-08-19 12:27:03"
}

/api/v1/users/{userId}/groups POST

Users can be part of multiple groups, but you can only add one user to a single group at a time.

Request

Parameter Description Type Required
group_id Unique group ID. Int True

Response

Parameter Description Type
attached Array with group IDs of groups the user has been added to. Array
detached Array with group IDs of groups the user has been removed from. Array
updated - Array

Check if user is part of a group


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/groups/6" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \ 
  -H 'Authorization: Bearer xP9kl1nxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-type'  => 'application/json', 
        'Authorization' => 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/groups/6', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/groups/6', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer xP9kl1nxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/groups/6', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "exists": false,
    "success": true,
    "timestamp": "2019-08-16 17:55:14"
}

/api/v1/users/{userId}/groups/{groupId} GET

Response

Parameter Description Type
exists True, if user is part of the group. Bool
success True, if request was successful. Bool

Remove user from a group


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/groups/6" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/users/2/groups/6', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/users/2/groups/6', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'DELETE',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/groups/6', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-16 17:26:33"
}

/api/v1/users/{userId}/groups/{groupId} DELETE

Response

Parameter Description Type
success True, if user was successfully removed from a group. Bool

Conversation (Private or group chats)

Gigaaa does not only allow conversations between the assistant and users, but also between users. Conversations can either be private between two users (i. e. type = 1) or be a group conversation (i. e. type = 2). While users are restricted to have only one private conversation with each user, they can have as many group conversations as they like. Even if a group conversation just contains two users.

Note: Sending messages is always based on a conversation. Messages are always stored in relation to a conversation, even if you want to send a message directly to a user.

Basic Services Structure and Parameters

Parameter Description Type Required
user_ids An array with all user ids of the participating users. Must contain between 1 and 120 users for group conversations and 1 user for private conversations. The user creating the request will automatically be added. Array True
title Title of the conversation. Must be between 1 and 150 chars. String True
image Main image of the conversation. String True
type To indicate if the conversation is private or not. Can be 1 for private and 2 for group conversations. Value cannot be changed after a conversation is created. Int True
mood_id If the conversation is related to a Mood, the ID will added. Int False
preview_image For private conversations, the preview image will be the profile image of your conversation counter part. For group conversations, the conversation image can be set by the participating users. The preview image is a smaller version of the original image. URL False

List all user conversations


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations?page=2&per_page=5" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/conversations?page=2&per_page=5', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/conversations?page=2&per_page=5', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversations?page=2&per_page=5", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "current_page": 1,
    "data": [ /* List of Conversations. */ ],
    "first_page_url": "https://api.gigaaa.link/api/v1/conversations?page=1",
    "from": 1,
    "last_page": 6,
    "last_page_url": "https://api.gigaaa.link/api/v1/conversations?page=6",
    "next_page_url": "https://api.gigaaa.link/api/v1/conversations?page=2",
    "path": "https://api.gigaaa.link/api/v1/conversations",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20,
    "total": 108,
    "timestamp": "2019-08-02 13:20:19"
}

/api/v1/conversations GET

Request

Parameter Description Type Required
page Current page of the conversation list. Int False
per_page Amount of conversations that should be returned per page. Int False
filter Free text to filter the conversation list. Int False

Response

Parameter Description Type
current_page Number of the current page. Int
data List of all conversations. Array
first_page_url Link used for pagination. URL
from Index, which indicate where the current selection starts. Int
last_page Number of the last page. Int
last_page_url Link used for pagination. URL
next_page_url Link used for pagination. URL
path URL to the current page. URL
per_page Amount of conversations displayed per page. Int
prev_page_url Link used for pagination. URL
to Index, which indicate where the current selection ends. Int
total Total amount of conversations. Int

Create a new private conversation


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ 
          "user_ids": [12008], 
          "type": 1 
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'type'      => 1,
        'user_ids'  => [12008],
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/conversations', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 
    'type': 1, 
    'user_ids': [12008] 
}

requests.post('/api/v1/conversations', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "type": 1,
        "user_ids": [12008]
    })
};

fetch("/api/v1/conversations", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "updated_at": "2019-08-19 13:22:52",
    "created_at": "2019-08-19 13:22:52",
    "id": 2445,
    "messages": [/* List of all Messages. */],
    "users": [/* List of User Objects. */],
    "timestamp": "2019-08-19 13:22:52"
}

/api/v1/conversations POST

To open a new private conversation, you can either create a new private conversation or you can simply send a message to a user. This will automatically create a new private conversation unless a conversation between those users already exists.

Request

Parameter Description Type Required
user_ids Array with user IDs that will be added to the conversation. (Only pass a single user ID to create a private conversation.) Array True, on creation.
user_id.* Unique user ID. Int True
title Title of the conversation. String False
image Image of the conversation. Image False
type Type of the conversation. (1 = Private, 2 = Group) Int True

Response

Parameter Description Type
id Unique conversation ID. Int
messages Array of all messages. Array
users Array with information for both users. Array

Create a new group conversation


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ 
          "user_ids": [12007, 12008, 12009], 
          "type": 2, 
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'type'      => 2,
        'user_ids'  => [12007, 12008, 12009],
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/conversations', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 
    'type': 2, 
    'user_ids': [12007, 12008, 12009] 
}

requests.post('/api/v1/conversations', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "type": 2,
        "user_ids": [12007, 12008, 12009]
    })
};

fetch("/api/v1/conversations", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "type": 2,
    "updated_at": "2019-08-19 13:25:26",
    "created_at": "2019-08-19 13:25:26",
    "id": 2446,
    "timestamp": "2019-08-19 13:25:26"
}

/api/v1/conversations POST

Group conversations can have up to 120 users and must have at least two users on creation. Creating a group conversation works very similar to the private conversation, except type must be set to 2 and the limitation on user_ids is lifted.

When new users are added, they will get notified and are able to contribute to your group chat right afterwards.

Request

Parameter Description Type Required
user_ids Array with user IDs that will be added to the conversation. Array True, on creation.
user_id.* Unique user ID. Int True
title Title of the conversation. String False
image Image of the conversation. Image False
type Type of the conversation. (1 = Private, 2 = Group) Int True

Response

Parameter Description Type
id Conversation ID. Int
type Type of conversation. Int

Receive a conversation


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations/2387" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/conversations/2387', $options);


import requests

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

requests.get('/api/v1/conversations/2387', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversations/2387", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 2446,
    "mood_id": null,
    "activity_id": null,
    "title": null,
    "block": 0,
    "type": 2,
    "preview_image": null,
    "created_at": "2019-08-19 13:25:26",
    "updated_at": "2019-08-19 13:25:26",
    "additional_users": [/* List of all Users, excluding the User who created the Conversation. */],
    "heading": "Peter, Jenny",
    "preview_image_url": "http://via.placeholder.com/200x200",
    "preview_image_url_small": "http://via.placeholder.com/200x200?size=small",
    "heading_with_links": "<a href=\"#/users/2519\">Peter/a>, <a href=\"#/users/2528\">Jenny</a>",
    "can_edit": true,
    "unread_messages_for_current_user_count": 0,
    "user_pivot": {
        "id": 4019,
        "user_id": 2521,
        "conversation_id": 2446,
        "mute": 0,
        "created_at": "2019-08-19 13:25:26",
        "updated_at": "2019-08-19 13:25:26"
    },
    "users": [/* List of all Users. */],
    "timestamp": "2019-08-19 13:26:23"
}

/api/v1/conversations/{conversationId} GET

Response

Parameter Description Type Required
id Unique conversation ID. Int
mood_id If the conversation is related to a Mood, the ID will added. Int
activity_id - Int
title Title of the conversation. String
block Determines, if the resource is blocked. Int
type Type of the conversation. Int
preview_image Preview image of the conversation. String
conversation_created_at Creation date of the conversation. String
messages Array of all messages. Array
additional_users Array of all additional users. Array
heading Heading of the conversation. (Default are all names of the users, separated by commas.) String
preview_image_url Link to the conversation preview image. URL
preview_image_url_small Link to the small version of the conversation preview image. URL
heading_with_links Heading of the conversation with the user's names wrapped by a link to their respective profiles. String
can_edit True, if the current user can edit the conversation. Bool
unread_messages_for_current_user_count Amount of unread messages the current user has in this conversation. Int
user_pivot User pivot table. Object
users Array of all users participating in this conversation. Array

Update conversation


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations/123" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "title": "New conversation title" }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ],
    'json' => [
        'title' => 'New conversation title'
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/conversations/123', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'title': 'New conversation title' }

requests.put('/api/v1/conversations/123', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "title": "New conversation title"
    })
};

fetch("/api/v1/conversations/123", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2022-12-31 16:22:54"
}

/api/v1/conversations/{conversationId} PATCH

Updating a conversation allows you to change the displaying title and image. You can also add or remove users from group chats.

To add or remove users, you need to add user_ids array to your request holding all user ids. Your array will be synced with all members of the group. It is not possible to just send the users you want to remove or add. Also, you cannot remove yourself from a chat at this moment.

Response

Parameter Description Type
success True, if conversation was successfully updated. Bool

Executing mixed actions


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations" \
  -XPATCH \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "action": "mark_all_messages_as_read_for_current_user" }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'action' => 'mark_all_messages_as_read_for_current_user'
    ]
];

$client = new \GuzzleHttp\Client();
$client->patch('/api/v1/conversations', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'action': 'mark_all_messages_as_read_for_current_user' }

requests.patch('/api/v1/conversations', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PATCH",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "action": "mark_all_messages_as_read_for_current_user"
    })
};

fetch("/api/v1/conversations", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "count": 0,
    "timestamp": "2022-12-31 16:22:54"
}

/api/v1/conversations/{conversationId} PATCH

When you receive a message, it will be marked as "unread". When you open a conversation and the message is loaded, it will be marked as "read" and will be removed from your notification panel. If you receive a large amount of messages, it can be exhausting to scroll through the entire chat history to mark them all as "read". So we give users the possibility to mark them all as read at once. Send the action => mark_all_messages_as_read_for_current_user as a PATCH request to the conversation endpoint.

Request

Parameter Description Type Required
action Select one action from the table below. String True

Response

Parameter Description Type
success True, if request was successful. Bool
count Count of performed actions. Int

Actions

Parameter Description
mark_all_messages_as_read_for_current_user Marks all unread messages as read for the requesting user.
report_spam Marks all unread messages as read for the requesting user.
toggle_mute Mutes/Unmutes notifications for this conversation for the requesting user.

We will define more options to deal with conversations and messages in the feature.

Delete conversations


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations/123" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/conversations/123', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/conversations/123', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversations/123", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2022-12-31 16:22:54"
}

/api/v1/conversations/{conversationId} DELETE

Private and group conversations can be deleted at any time by anyone who is part of it. If a conversation is deleted, all related messages will be removed as well.

Response

Parameter Description Type
success True, if the conversation was deleted successfully. Bool

Remove user from conversation


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations/215/users/74" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ] 
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/conversations/215/users/74', $options);


import requests

headers = { 
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

requests.delete('/api/v1/conversations/215/users/74', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversations/215/users/74", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "status": true,
    "timestamp": "2019-08-20 11:23:53"
}

/api/v1/conversations/{conversationId}/users/{userId} DELETE

Response

Parameter Description Type
success True, if the user was successfully removed from the conversation. Bool

Get all conversation messages


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversation-messages?conversation_id=222" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/conversation-messages?conversation_id=222', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/conversation-messages?conversation_id=222', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversation-messages?conversation_id=222", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "data": [
        {
            "id": 101,
            "conversation_id": 8,
            "user_id": 7,
            "title": null,
            "content": "<p>Content</p>",
            "type": 0,
            "additional": null,
            "published": 1,
            "block": 0,
            "created_at": "2018-01-16 09:22:14",
            "updated_at": "2018-01-16 09:22:14",
            "is_my": false,
            "date_string": "1 year ago",
            "image_url": "",
            "image_url_preview": "",
            "user": {/* User who sent the message. */},
            "message_seen_state": [
                {
                    "id": 62,
                    "user_id": 2,
                    "message_id": 101,
                    "created_at": "2018-01-16 11:45:14",
                    "updated_at": "2018-01-16 11:45:14"
                }
            ]
        },
        ... more messages
    ],
    "timestamp": "2019-08-02 19:00:15"
}

/api/v1/conversation-messages?conversation_id=123 GET

Next to our classical pagination parameters, you have some more options to filter the conversation page.

Request

Parameter Description Type Required
conversation_id The id of the conversation for which the messages should be returned for. Int True
beforeId If set, only messages before this id will be displayed. Ids are always ongoing. Int False
afterId If set, only messages after this id will be displayed. Int False
page Used to define a specific page. Int False
per_page Amount of pages that should be returned. Int False

Response

Parameter Description Type Required
id Unique message ID. Int
conversation_id Unique ID of conversation. Int
user_id Unique user ID of user who sent the message. Int
title Title of the conversation message. String
content Content of the message. String
type Content type of the message. (Message Types) Int
additional - Array
published Publication status of the message. Int
block Determines, if the resource is blocked. Int
message_seen_state Array of all user's message-seen-state. Array
user User Object with all user properties. Object
is_my True, if message was sent by current user. Bool
date_string Date string (i.e. '1 year ago' or a specific time.) String
image_url Link to the message's image, if available. URL
image_url_preview Link to the message's preview image, if available. URL

Create text and media messages


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversation-messages" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{
         "conversation_id": 2387, 
         "content": "Inspire me."
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'conversation_id'  => 2387,
        'content'          => "Inspire me.",
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/conversation-messages', $options);


import json
import requests

headers = {
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = {
    'conversation_id': 2387,
    'content': 'Inspire me.'
}

requests.post('/api/v1/conversation-messages', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "content": "Inspire me.",
        "conversation_id": 2387
    })
};

fetch("/api/v1/conversation-messages", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "content": "<p>Test</p>",
    "user_id": 2,
    "published": 1,
    "conversation_id": 2388,
    "updated_at": "2019-08-02 16:51:52",
    "created_at": "2019-08-02 16:51:52",
    "id": 6234,
    "is_my": true,
    "date_string": "16:51",
    "image_url": "",
    "image_url_preview": "",
    "user": {/* User profile of who posted the entry. */},
    "conversation": {
        "id": 2388,
        "mood_id": null,
        "activity_id": null,
        "title": null,
        "block": 0,
        "type": 2,
        "preview_image": null,
        "created_at": "2019-08-02 16:45:15",
        "updated_at": "2019-08-02 16:45:15"
    },
    "timestamp": "2019-08-02 16:51:52"
}

/api/v1/conversation-messages POST

You can post messages to a conversation by passing the conversation_id. If you want to post a message to private conversation between two users, you can alternatively pass the user_id of the receiving user.

Request

Parameter Description Type Required
content The text message of the message. String True, if no file is present.
conversation_id The id of the conversation for which the messages should be created for. Int True, if user_id not present.
user_id The user who should receive the message Int True, if conversation_id no present.
file If set, only messages after this id will be displayed. File False
type Content type of the message. (Message Types) Int True, if file not present.

Response

Parameter Description Type
content Content of the message. String
user_id User ID of user who send the message. Int
published Determines, whether the message is published or not. Int
conversation_id Conversation ID of conversation that the message was sent to. Int
id Unique message ID. Int
is_my True, if message was sent by current user. Bool
date_string Time, when the message was sent. (HH:MM) String
user User Object with all user properties. Object
conversation Conversation Object with all conversation properties. Object
image_url URL to image, if available. URL
image_url_preview URL to image preview, if available. URL

Message Types

Gigaaa allows you to not only send text, but also media messages. If you send a file, make sure, to pass the type and the file attributes.

Type Value
Text 0
Image 1
Audio 2
Video 3
Location 4 (Not supported yet, coming soon.)
File 5
Contact 6 (Not supported yet, coming soon.)

Get a conversation message


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversation-messages/123" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/conversation-messages/123', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

requests.get('/api/v1/conversation-messages/123', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversation-messages/123", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 101,
    "conversation_id": 8,
    "user_id": 7,
    "title": null,
    "content": "<p>Very important message.</p>",
    "type": 0,
    "additional": null,
    "published": 1,
    "block": 0,
    "created_at": "2018-01-16 09:22:14",
    "updated_at": "2018-01-16 09:22:14",
    "is_my": false,
    "date_string": "1 year ago",
    "image_url": "",
    "image_url_preview": "",
    "conversation": {/* Converation details. */},
    "timestamp": "2019-08-02 18:29:56"
}

/api/v1/conversation-messages/{conversationMessageId} GET

Use this endpoint, if you just want a single message to return.

Response

Parameter Description Type
id Unique message ID. Int
conversation_id Unique conversation ID. Int
user_id Unique user ID. Int
title Title of the message. String
content Content of the message. String
type Content type of the message. (Message Types) Int
additional - Array
published Publication status of message. Int
block Determines, if the resource is blocked. Int
is_my True, if message was sent by current user. Bool
date_string Date string (i.e. '1 year ago') String
image_url Link to the message's image, if available. URL
image_url_preview Link to the message's preview image, if available. URL
conversation Conversation Object with all conversation properties. Object

Update a message


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversation-messages/101" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "content": "My updated content" }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'content' => "My updated content",
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/conversation-messages/101', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = { 'content': 'My updated content' }

requests.put('/api/v1/conversation-messages/101', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "content": "My updated content"
    })
};

fetch("/api/v1/conversation-messages/101", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-02 18:34:00"
}

/api/v1/conversation-messages/{conversationMessageId} PUT

At this stage, only the content can be changed. If you want to move your message to another conversation or change a file, you need to delete the original message and create a new one.

Request

Parameter Description Type Required
content The content of the message. String True

Response

Parameter Description Type
success True, if updating the message was successful. Bool

Delete message


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversation-messages/123" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/conversation-messages/123', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

requests.delete('/api/v1/conversation-messages/123', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversation-messages/123", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-02 18:38:45"
}

/api/v1/conversation-messages/{conversationMessageId} DELETE

Response

Parameter Description Type
success True, if deleting the message was successful. Bool

Get conversation image


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations/215/images/2a71b22f-e8ed-4eca-b93d-7ded410e3005" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ] 
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/conversations/215/images/2a71b22f-e8ed-4eca-b93d-7ded410e3005", $options);


import requests

headers = {
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/conversations/215/images/2a71b22f-e8ed-4eca-b93d-7ded410e3005', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversations/215/images/2a71b22f-e8ed-4eca-b93d-7ded410e3005', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

The response will be the image file.

/api/v1/conversations/{conversationId}/images/{uuid}/{size?} GET

Note: The {size?} parameter is optional.

Response

The response will be the image file.

Get a conversation mood


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations/moods/13" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/conversations/moods/13', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/conversations/moods/13', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversations/moods/13", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{

}

/api/v1/conversations/moods/{moodsId} GET

Response

Parameter Description Type

Get or create a conversation mood


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations/moods/13/get-or-create" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/conversations/moods/13/get-or-create', $options);


import requests
headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/conversations/moods/13/get-or-create', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversations/moods/13/get-or-create", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{

}

/api/v1/conversations/moods/{moodsId}/get-or-create GET

Response

Parameter Description Type

Get message image


# With shell, you can just pass the correct header with each request

curl "/api/v1/conversations/215/images/image.jpg" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ] 
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/conversations/215/images/image.jpg', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/conversations/215/images/image.jpg', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/conversations/215/images/image.jpg", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

The response will be the image file.

/api/v1/message/{id}/{filename}n/{size?} GET

Note: The {size?} parameter is optional.

Response

The response will be the image file.

Addresses

Get User addresses


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/addresses" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/addresses', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/addresses', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/addresses', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "0": {
        "id": 148,
        "title": "Berlin Kreuzberg",
        "street": "Oppelner Straße",
        "street_number": null,
        "city": "Berlin",
        "postal_code": "10997",
        "country_id": 1,
        "type": 0,
        "user_id": 2521,
        "created_at": "2019-08-19 12:41:34",
        "updated_at": "2019-08-19 12:41:34",
        "point": null
    },
    "timestamp": "2019-08-19 12:42:11"
}

/api/v1/users/{userId}/addresses GET

Response

Parameter Description Type
id Unique address ID. Int
user_id Unique user ID. Int
title Address Title. String
street Street Name. String
street_number Street Number. String
city Name of the City. String
postal_code Postal Code of the city. String
country_id Unique country ID. Int
type Address type (List of all Address Types) Int

Create address


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/addresses" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ 
        "city":"Berlin", 
        "postal_code":"10997", 
        "country_id":83 
      }'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ],
    'json' => [
        'city'        => 'Berlin', 
        'portal_code' => '10997', 
        'country_id'  => 82
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/2/addresses', $options);
?>


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 
    'city': 'Berlin', 
    'portal_code': '10997', 
    'country_id': 82 
}

requests.post('/api/v1/users/2/addresses', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }, 
    body: JSON.stringify({
        'city': 'Berlin',
        'portal_code': '10997', 
        'country_id': 82
    })
};

fetch('/api/v1/users/2/addresses', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "title": "Berlin Kreuzberg",
    "street": "Oppelner Straße",
    "city": "Berlin",
    "postal_code": "10997",
    "country_id": 1,
    "user_id": 2521,
    "updated_at": "2019-08-19 12:41:34",
    "created_at": "2019-08-19 12:41:34",
    "id": 148,
    "timestamp": "2019-08-19 12:41:34"
}

/api/v1/users/{userId}/addresses POST

Request

Parameter Description Type Required
title Address Title. String False
street Street Name. String True
street_number Street Number. String False
city Name of the city. String True
postal_code Postal Code of the city. String True
country_id Unique Country ID. Int True
type Address type (List of all Address Types) Int False

Response

Parameter Description Type
id Unique address ID. Int
user_id Unique user ID. Int
title Address Title. String
street Street Name. String
street_number Street Number. String
city Name of the city. String
postal_code Postal Code of the city. String
country_id Unique Country ID. Int
type Address type (List of all Address Types) Int

Address Types

Parameter Value
UNDEFINED 0
HOME 1
WORK 2
TRAINING 3
SCHOOL 4
PARTNER 5
PARENTS 6
FAMILY 7

Update specific addresses


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/addresses/2" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "title": "Berlin - Kreuzberg" }'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ], 
    'json' => [
        'title' => 'Berlin - Kreuzberg'
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/users/2/addresses/2', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'title': 'Berlin - Kreuzberg' }

requests.put('/api/v1/users/2/addresses/2', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'PUT',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }, 
    body: JSON.stringify({ "title": "Berlin - Kreuzberg" })
};

fetch('/api/v1/users/2/addresses/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-19 12:44:35"
}

/api/v1/users/{userId}/addresses/{addressId} PUT

Request

Parameter Description Type Required
title Address Title. String False
street Street Name. String False
street_number Street Number. String False
city Name of the city. String False
postal_code Postal Code of the city. String False
country_id Unique country ID. Int False

Response

Parameter Description Type
id Unique address ID. Int
user_id Unique user ID. Int
title Address Title. String
street Street Name. String
street_number Street Number. String
city Name of the city. String
postal_code Postal Code of the city. String
country_id Unique country ID. Int
type Address type (List of all Address Types) Int

Get a specific address


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/addresses/2" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/addresses/2', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/addresses/2', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/addresses/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 148,
    "title": "Berlin - Kreuzberg",
    "street": "Oppelner Straße",
    "street_number": null,
    "city": "Berlin",
    "postal_code": "10997",
    "country_id": 1,
    "type": 0,
    "user_id": 2521,
    "created_at": "2019-08-19 12:41:34",
    "updated_at": "2019-08-19 12:44:35",
    "point": null,
    "timestamp": "2019-08-19 12:50:00"
}

/api/v1/users/{userId}/addresses/{addressId} GET

Response

Parameter Description Type
id Unique address ID. Int
user_id Unique user ID. Int
title Address Title. String
street Street Name. String
street_number Street Number. String
city Name of the city. String
postal_code Postal Code of the city. String
country_id Unique country ID. Int
type Address type (List of all Address Types) Int

Delete addresses


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/addresses/2" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/users/2/addresses/2', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/users/2/addresses/2', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'DELETE',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/addresses/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-19 12:52:44"
}

/api/v1/users/{userId}/addresses/{addressId} DELETE

Response

Parameter Description Type
success True, if address was successfully deleted. Bool

Block Users

Get Blocked Users


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/blocked-users" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/blocked-users', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/blocked-users, headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/blocked-users', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "0": {
        "id": 2519,
        "name": "Peter",
        "language_id": 83,
        "block": 0,
        "created_at": "2019-08-15 12:43:26",
        "avatar_url": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback",
        "avatar_url_tiny": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback?size=tiny",
        "is_tester": false,
        "pivot": {
            "user_id": 2521,
            "blocked_user_id": 2519,
            "created_at": "2019-08-19 12:59:20",
            "updated_at": "2019-08-19 12:59:20"
        },
        "profile": {}
    },
    "timestamp": "2019-08-19 12:59:23"
}

/api/v1/users/{userId}/blocked-users GET

Response

Parameter Description Type
id Unique user ID. Int
name Username of blocked user. String
language_id Unique language ID. Int
block Determines, if the resource is blocked. Int
avatar_url URL to user image. URL
avatar_url_tiny URL to user image. (Returns smallest image size.) URL
is_tester Determines, whether the user is a tester. Bool
profile Profile Object with all profile properties. Object
pivot Pivot Object with all pivot table properties. Object

Check if a user is blocked by another user


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/blocked-users/15" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/blocked-users/15', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/blocked-users/15', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/blocked-users/15', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "blocked": true,
    "timestamp": "2019-08-19 13:03:37"
}

/api/v1/users/{userId}/blocked-users/{blockedUserId} GET

Response

Parameter Description Type
blocked True, if user is blocked by the other user. Bool

Block User


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/blocked-users/15" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/2/blocked-users/15', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.post('/api/v1/users/2/blocked-users/15', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/blocked-users/15', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-19 12:58:15"
}

/api/v1/users/{userId}/blocked-users/{blockedUserId} POST

Response

Parameter Description Type
success True, if user was successfully blocked. Int

Unblock User


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/blocked-users/15" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/users/2/blocked-users/15', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/users/2/blocked-users/15', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'DELETE',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/blocked-users/15', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-19 13:05:53"
}

/api/v1/users/{userId}/blocked-users/{blockedUserId} DELETE

Response

Parameter Description Type
success True, if user was successfully unblocked. Bool

Sync blocked users


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/blocked-users/sync" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "user_ids": [4, 7, 10] }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ], 
    'json' => [
        'user_ids' => [4, 7, 10]
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/users/2/blocked-users/sync', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = { 'user_ids': [4, 7, 10]' }

requests.put('/api/v1/users/2/blocked-users/sync', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'PUT',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }, 
    body: JSON.stringify({
        'user_ids': [4, 7, 10]
    })
};

fetch('/api/v1/users/2/blocked-users/sync', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-19 12:58:15"
}

/api/v1/users/{userId}/blocked-users/sync POST

If you like to sync all users, which are blocked/unblocked by a users, you can pass an array with user_ids. Be aware, if you have blocked a user, and he is not passed, he won't be blocked afterwards. This is a request to sync, not to attach or remove single values.

Request

Parameter Description Type Required
blocked_user_ids Array with all user_ids of the users which should be blocked. Array True
blocked_user_ids.* Unique User Id. Int False

Response

Parameter Description Type
success True, if the request was successful. Bool

Connected Accounts And Connected Account Providers

Get all connected account providers


# With shell, you can just pass the correct header with each request

curl "/api/v1/connected-account-providers" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/connected-account-providers', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/connected-account-providers', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/connected-account-providers', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "connected_account_providers": [
        {
            "id": 1,
            "name": "Facebook",
            "issuer": null,
            "max_accounts_per_user": 1,
            "description": "Connecting your Facebook Account with Gigaaa allows you to control [...]"
        },
        {/* .. another Connected Account Provider */},
        {/* .. another Connected Account Provider */}
    ],
    "timestamp": "2019-08-20 11:07:18"
}

/api/v1/connected-account-providers GET

Response

Parameter Description Type
id Unique connected account provider ID. Int
name Name of the connected account provider. String
issuer - String
max_accounts_per_user Limits how many user accounts can be connected. Int
description Description of the connected account provider. String

Get a connected account provider


# With shell, you can just pass the correct header with each request

curl "/api/v1/connected-account-providers/2" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/connected-account-providers/2', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/connected-account-providers/2', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/connected-account-providers/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "connected_account_provider": {
        "id": 2,
        "name": "Facebook",
        "issuer": null,
        "max_accounts_per_user": 1,
        "description": "Connecting your Facebook Account with Gigaaa allows you to control [...]"
    },
    "timestamp": "2019-08-20 11:09:47"
}

/api/v1/connected-account-providers/{connectedAccountProviderId} GET

Response

Parameter Description Type
connected_account_provider Object with all inherent connected account provider properties. Object
connected_account_provider.id Unique connected account provider ID. Int
connected_account_provider.name Name of the connected account provider. String
connected_account_provider.issuer - String
connected_account_provider.max_accounts_per_user Limits how many user accounts can be connected. Int
connected_account_provider.description Description of the connected account provider. String

Get a connected account


# With shell, you can just pass the correct header with each request

curl "/api/v1/connected-accounts/2" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/connected-accounts/2', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/connected-accounts/2', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/connected-accounts/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:


/api/v1/connected-accounts/{connectedAccountId} GET

Response

Parameter Description Type

Update a connected account


# With shell, you can just pass the correct header with each request

curl "/api/v1/connected-accounts/2" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "access_token": "k2JwXpuIopxxxxxxxxxxxxxx" }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ], 
    'json' => [
        'access_token' => 'k2JwXpuIopxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/connected-accounts/2', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'access_token': 'k2JwXpuIopxxxxxxxxxxxxxx' }

requests.put('/api/v1/connected-accounts/2', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'PUT',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }, 
    body: JSON.stringify({
        'access_token': 'k2JwXpuIopxxxxxxxxxxxxxx'
    })
};

fetch('/api/v1/connected-accounts/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true, 
    "timestamp": "2019-08-20 11:17:36"
}

/api/v1/connected-accounts/{connectedAccountId} PUT

Request

Parameter Description Type Required
accessToken Access Token String True

Response

Parameter Description Type
success True, if the request was successful. Bool

Delete a connected account


# With shell, you can just pass the correct header with each request

curl "/api/v1/connected-accounts/2" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/connected-accounts/2', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/connected-accounts/2', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'DELETE',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/connected-accounts/2', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true, 
    "timestamp": "2019-08-20 11:17:36"
}

/api/v1/connected-accounts/{connectedAccountId} DELETE

Response

Parameter Description Type
success True, if deleting the connected account was successful. Bool

Smart Home Devices

Gigaaa enables users to connect their accounts of different Smart Home Providers with the Gigaaa environment. If they do, Gigaaa and its services get access to the users devices from that provider.

At the moment, Smart Home Devices can't be directly added to Gigaaa, instead you have to use the app of the respective provider.

Connected devices can be used by Gigaaa, for example to control your devices using voice commands. There are two requirements for that to work:

Get all Smart Home Devices


# With shell, you can just pass the correct header with each request

curl "/api/v1/smart-home-devices"
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/smart-home-devices', $options);


import requests

headers = { \
    'Accept': 'application/json', \
    'Content-Type': 'application/json', \
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
}

requests.get('/api/v1/smart-home-devices', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/smart-home-devices", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "Innogy": {/* All Innogy Devices. */} 
}

/api/v1/smart-home-devices GET

This endpoint responds with all Smart Home Devices for the requesting user, grouped by their Smart Home Device Providers.

Response

Parameter Description Type
provider Smart Home Device Provider with all inherent properties. Object

Contact Requests and Contacts

Get Contact Requests


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/contact-requests" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/contact-requests', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/contact-requests', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/contact-requests", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "contact_request": [
        {
            "id": 1177,
            "user_id": 2521,
            "contact_user_id": 2528,
            "status": 0,
            "status_changed_at": null,
            "message": null,
            "created_at": "2019-08-19 13:49:14",
            "updated_at": "2019-08-19 13:49:14",
            "user": {
                "id": 2521,
                "name": "Peter",
                "language_id": 83,
                "block": 0,
                "created_at": "2019-08-15 17:25:31",
                "avatar_url": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback",
                "avatar_url_tiny": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback?size=tiny",
                "is_tester": false,
                "profile": {}
            }
        }
    ],
    "users": [/* Array with users. */],
    "success": true,
    "timestamp": "2019-08-19 13:52:57"
}

/api/v1/users/{userId}/contact-requests GET

Shows open and pending contact request for the {userId}.

Request

Parameter Description Type Required
filter Can be used to filter the response. String False

Response

Parameter Description Type
success True, if request was successful. Bool
contact_request Contact Request Object with all inherent properties. Object
users Array of users that sent a request. Array

Check if a contact request between two users exists


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/contact-requests/3" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/contact-requests/3', $options);


import requests

headers = { 
    'Accept': 'application/json',
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/contact-requests/3', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/contact-requests/3", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "contact_request": true,
    "success": true,
    "timestamp": "2019-08-19 13:56:27"
}

/api/v1/users/{userId}/contact-requests/{contactUserId} GET

Response

Parameter Description Type
success True, if request was successful. Bool
contact_request True, if contact request exists between two users. Bool

Send contact request


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/contact-requests/3" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/2/contact-requests/3', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.post('/api/v1/users/2/contact-requests/3', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/contact-requests/3", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "contact_request": {
        "contact_user_id": 2528,
        "user_id": 2521,
        "updated_at": "2019-08-19 13:49:14",
        "created_at": "2019-08-19 13:49:14",
        "id": 1177
    },
    "success": true,
    "timestamp": "2019-08-19 13:49:14"
}

/api/v1/users/{userId}/contact-requests/{contactUserId} POST

Response

Parameter Description Type
success True, if sending the contact request was successful. Bool
contact_request Contact Request Object with all properties. Object
contact_request.contact_user_id Unique user id of user that receives the request. Int
contact_request.user_id Unique user ID of user that send the request. Int
contact_request.created_at Timestamp of request creation date. String
contact_request.updated_at Timestamp of last update. String
id Unique contact request ID. Int

Withdraw contact request


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/contact-requests/3" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/users/2/contact-requests/3', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/users/2/contact-requests/3', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/contact-requests/3", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "success": true,
    "timestamp": "2019-08-19 13:59:47"
}

/api/v1/users/{userId}/contact-requests/{contactUserId} DELETE

Response

Parameter Description Type
success True, if withdrawing the contact request was successful. Bool

Accept Contact Request


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/contact-requests/3/accept" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/users/2/contact-requests/3/accept', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.put('/api/v1/users/2/contact-requests/3/accept', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/contact-requests/3/accept", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "success": true,
    "timestamp": "2019-08-19 14:03:18"
}

/api/v1/users/{userId}/contact-requests/{contactUserId}/accept PUT

Response

Parameter Description Type
success True, if contact request was accepted successfully. Bool

Reject Contact Request


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/contact-requests/3/reject" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/users/2/contact-requests/3/reject', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.put('/api/v1/users/2/contact-requests/3/reject', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "reject": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/contact-requests/3/reject", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "success": true,
    "timestamp": "2019-08-19 14:03:18"
}

/api/v1/users/{userId}/contact-requests/{contactUserId}/reject PUT

Response

Parameter Description Type
success True, if contact request was rejected successfully. Bool

Get User Contact


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/contacts" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/contacts', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/contacts', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/contacts", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "contacts": [/* Array with User Objects. */],
    "success": true,
    "timestamp": "2019-08-19 14:11:18"
}

/api/v1/users/{userId}/contacts GET

Request

Parameter Description Type Required
filter Free text to filter the results. String False
except_ids User ids which should be excluded from the search results. Array False
except_ids.* Unique user ID. Int False

Response

Parameter Description Type
success True, if request was successful. Bool
contacts Array with user objects. Array

Remove contact


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/contacts/5" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/users/2/contacts/5', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/users/2/contacts/5', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/contacts/5", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "success": true,
    "timestamp": "2019-08-19 14:11:18"
}

/api/v1/users/{userId}/contacts/{contactUserId} DELETE

Response

Parameter Description Type
success True, if contact was successfully removed. Bool

Contact Requests (Alternative Routes)

Withdraw contact request


# With shell, you can just pass the correct header with each request

curl "/api/v1/contact-requests/3" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/contact-requests/3', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

requests.delete('/api/v1/contact-requests/3', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/contact-requests/3", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "success": true,
    "timestamp": "2019-08-19 13:59:47"
}

/api/v1/contact-requests/{contactUserId} DELETE

Response

Parameter Description Type
success True, if withdrawing the contact request was successful. Bool

Accept contact request


# With shell, you can just pass the correct header with each request

curl "/api/v1/contact-requests/3/accept"
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/contact-requests/3/accept', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

requests.put('/api/v1/contact-requests/3/accept', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/contact-requests/3/accept", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "success": true,
    "timestamp": "2019-08-19 14:03:18"
}

/api/v1/contact-requests/{contactUserId}/accept PUT

Response

Parameter Description Type
success True, if contact request was accepted successfully. Bool

Reject contact request


# With shell, you can just pass the correct header with each request

curl "/api/v1/contact-requests/3/reject" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/contact-requests/3/reject', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.put('/api/v1/contact-requests/3/reject', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "reject": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/contact-requests/3/reject", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "success": true,
    "timestamp": "2019-08-19 14:03:18"
}

/api/v1/contact-requests/{contactUserId}/reject PUT

Response

Parameter Description Type
success True, if contact request was rejected successfully. Bool

Phones

The specification of related endpoints will change soon. Please stay updated.

Get User phones


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/phones" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/phones', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/phones', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/phones", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "0": {
        "id": 4,
        "phone_prefix": "250",
        "phone": "111111",
        "phone_mobile_prefix": "250",
        "phone_mobile": "222222",
        "user_id": 2521,
        "created_at": "2019-08-19 14:20:03",
        "updated_at": "2019-08-19 14:20:03"
    },
    "1": {/* another Phone Object */},
    "2": {/* another Phone Object */},
    "timestamp": "2019-08-19 14:22:02"
}

/api/v1/users/{userId}/phones GET

Response

Parameter Description Type
phone Phone number. String
phone_prefix Phone prefix. String
phone_mobile Mobile phone number. String
phone_mobile_prefix Mobile phone prefix. String
user_id Unique user ID. Int
id Unique phone ID. Int

Create phone


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/phones" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ 
        "phone": "222222", 
        "phone_prefix": "123" 
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'json' => [
        'phone'        => '222222', 
        'phone_prefix' => '123'
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/2/phones', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 
    'phone': '222222', 
    'phone_prefix': '123' 
}

requests.post('/api/v1/users/2/phones', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }, 
    body: JSON.stringify({
        'phone': '222222', 
        'phone_prefix': '123'
    })  
};

fetch("/api/v1/users/2/phones", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "phone_prefix": "123",
    "phone": "222222",
    "user_id": 2521,
    "updated_at": "2019-08-19 14:20:03",
    "created_at": "2019-08-19 14:20:03",
    "id": 4,
    "timestamp": "2019-08-19 14:20:03"
}

/api/v1/users/{userId}/phones POST

Request

Parameter Description Type Required
phone Phone number. String True, if phone_prefix is given.
phone_prefix Phone prefix. String True, if phone is given.
phone_mobile Mobile phone number. String True, if phone_mobile_prefix is given.
phone_mobile_prefix Mobile phone prefix. String True, if phone_mobile is given.

Response

Parameter Description Type
phone Phone number. String
phone_prefix Phone prefix. String
phone_mobile Mobile phone number. String
phone_mobile_prefix Mobile phone prefix. String
user_id Unique user ID. Int
id Unique phone ID. Int

Get phone number


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/phones/4" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/phones/4', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/phones/4', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/phones/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "id": 4,
    "phone_prefix": "250",
    "phone": "111111",
    "phone_mobile_prefix": "250",
    "phone_mobile": "222222",
    "user_id": 2521,
    "created_at": "2019-08-19 14:20:03",
    "updated_at": "2019-08-19 14:20:03",
    "timestamp": "2019-08-19 14:25:16"
}

/api/v1/users/{userId}/phones/{phoneId} GET

Response

Parameter Description Type
phone Phone number. String
phone_prefix Phone prefix. String
phone_mobile Mobile phone number. String
phone_mobile_prefix Mobile phone prefix. String
user_id Unique user ID. Int
id Unique phone ID. Int

Update phone number


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/phones/4" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ 
        "phone": "121212", 
        "phone_prefix": "123" 
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'json' => [
        'phone'        => '121212', 
        'phone_prefix' => '123'
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/users/2/phones/4', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 
    'phone': '121212', 
    'phone_prefix': '123' 
}

requests.put('/api/v1/users/2/phones/4', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }, 
    body: JSON.stringify({
        'phone': '121212', 
        'phone_prefix': '123'
    })
};

fetch("/api/v1/users/2/phones/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "success": true,
    "timestamp": "2019-08-19 14:27:09"
}

/api/v1/users/{userId}/phones/{phoneId} PUT

Request

Parameter Description Type Required
phone Phone number. String True, if phone_prefix is given.
phone_prefix Phone prefix. String True, if phone is given.
phone_mobile Mobile phone number. String True, if phone_mobile_prefix is given.
phone_mobile_prefix Mobile phone prefix. String True, if phone_mobile is given.

Response

Parameter Description Type
success True, if phone was successfully updated. Bool

Delete phone number


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/phones/4" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/users/2/phones/4', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/users/2/phones/4', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    }
};

fetch("/api/v1/users/2/phones/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

To reduced necessary requests, the participating users and the latest messages will automatically be added to your request.

{
    "success": true,
    "timestamp": "2019-08-19 14:30:46"
}

/api/v1/users/{userId}/phones/{phoneId} DELETE

Response

Parameter Description Type
success True, if phone was successfully deleted. Bool

Saved Users

Get Saved Users


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/saved-users" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/saved-users', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json',
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/saved-users', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/saved-users', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "0": {
        "id": 2519,
        "name": "Peter",
        "language_id": 83,
        "block": 0,
        "created_at": "2019-08-15 12:43:26",
        "avatar_url": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback",
        "avatar_url_tiny": "https://mp2.gigaaa.link/api/v1/users/avatars/fallback?size=tiny",
        "is_tester": false,
        "pivot": {
            "saved_user_id": 2521,
            "user_id": 2519,
            "created_at": "2019-08-19 14:42:23",
            "updated_at": "2019-08-19 14:42:23"
        },
        "profile": null
    },
    "1": {/* .. another User Object */)},
    "2": {/* .. another User Object */)},
    "timestamp": "2019-08-19 14:48:37"
}

/api/v1/users/{userId}/saved-users GET

Response

Parameter Description Type
success True, if request was successful. Bool
users Array with all saved users. Array

Check if a user is saved by another user


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/saved-users/33" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/users/2/saved-users/33', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/users/2/saved-users/33', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/saved-users/33', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "exists": true,
    "success": true,
    "timestamp": "2019-08-19 14:45:28"
}

/api/v1/users/{userId}/saved-users/{savedUserId} GET

Response

Parameter Description Type
exists True, if user is saved by the other user. Bool
success True, if request was successful. Bool

Save User


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/saved-users/33" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \


<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/2/saved-users/33', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.post('/api/v1/users/2/saved-users/33', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/saved-users/33', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-19 14:42:23"
}

/api/v1/users/{userId}/saved-users/{savedUserId} POST

Response

Parameter Description Type
success True, if saving the user was successful. Bool

Remove saved User


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/saved-users/33" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/users/2/saved-users/33', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/users/2/saved-users/33', headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'DELETE',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }
};

fetch('/api/v1/users/2/saved-users/33', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": 1,
    "timestamp": "2019-08-19 14:52:11"
}

/api/v1/users/{userId}/saved-users/{savedUserId} DELETE

Response

Parameter Description Type
success Returns 1, if saving the user was successful. Int

Toggle saved user state

/api/v1/users/{userId}/saved-users/{savedUserId} PUT

Sync saved users


# With shell, you can just pass the correct header with each request

curl "/api/v1/users/2/saved-users/sync" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "user_ids": [4, 7, 10] }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    ], 
    'json' => [
        'user_ids' => [4, 7, 10]
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/users/2/saved-users/sync', $options);


import json
import requests

headers = { 
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = { 'user_ids' : [4, 7, 10] }

requests.post('/api/v1/users/2/saved-users/sync', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
    }, 
    body: JSON.stringify({
        'user_ids': [4, 7, 10]
    })
};

fetch('/api/v1/users/2/saved-users/sync', options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "success": true,
    "timestamp": "2019-08-19 12:58:15"
}

/api/v1/users/{userId}/saved-users/sync POST

If you like to sync all users, which are saved by a users, you can pass an array with user_ids. Be aware, if you have saved a user, and he is not passed, he won't be saved afterwards. This is a request to sync, not to attach or remove single values.

Request

Parameter Description Type Required
saved_user_ids Array with all user_ids of the users which should be saved. Array True
saved_user_ids.* Unique user ID. Int False

Response

Parameter Description Type
success True, if the request was successful. Bool

Listing

Listings are basically just normal lists that can hold zero, one or multiple listing items.

Note: Core developers can create, view, update and delete listings for other users.

Get all listings

Note:


# With shell, you can just pass the correct header with each request

curl "/api/v1/listings" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
  -d '{
          "user_id": 15, 
          "filter": "grocery"
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ], 
    'json' => [
        'user_id'   => 2, 
        'filter'    => 'grocery'
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/listings', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = {
    'user_id' => 2,
    'filter': 'grocery'
}

requests.get('/api/v1/listings', data=json.dumps(payload), headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "user_id": 2, 
        "filter": "grocery"
    })
};

fetch("/api/v1/listings", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:


[
    {
        "id": 1,
        "user_id": 2,
        "title": "Grocery list",
        "description": "Things i need to buy.",
        "published": 1,
        "created_at": "2019-10-01 10:49:07",
        "updated_at": "2019-10-01 10:49:07",
        "listing_items": [
            {
                "id": 1,
                "listing_id": 1,
                "title": "Buy chesse",
                "deadline": null,
                "done": 1,
                "published": 1,
                "created_at": "2019-10-01 10:49:07",
                "updated_at": "2019-10-01 10:49:07"
            },
            {/* .. another ListingItem */}
        ]
    },
    {/* .. another Listing */}
]

/api/v1/listings GET

Request Parameter

Parameter Description Type Required
user_id Unique User ID. Int True
filter Can be used to filter the response by title. String False

Response

Parameter Description Type
id Unique Listing ID. Int
user_id Unique User ID. Int
title Title of the Listing. String
description Description of the listing. String
published Publication status of the listing. Int
listing_items Array with all ListingItems that belong to the listing. Array

Create a listing


# With shell, you can just pass the correct header with each request

curl "/api/v1/listings" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{
          "user_id": 15, 
          "title": "Grocery list",
          "description": "Stuff i need to buy.",
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'user_id'       => 15, 
        'title'         => 'Grocery List',
        'description'   => 'Stuff i need to buy.'
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/listings', $options);


import json
import requests

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = {
    'user_id': 15,
    'title': 'Grocery List', 
    'description': 'Stuff i need to buy.'
}

requests.post('/api/v1/listings', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "user_id": 15,
        "title": "Grocery list", 
        "description": "Stuff i need to buy."
    })
};

fetch("/api/v1/listings", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 54,
    "user_id": 15,
    "title": "Groceries list",
    "description": "Stuff i need to buy.", 
    "published": 1,
    "updated_at": "2019-10-01 12:34:27",
    "created_at": "2019-10-01 12:34:27"
}

/api/v1/listings POST

Note: Core Developers can create Listings for other users.

Request

Parameter Description Type Required
user_id Unique User ID. Int True
title Title of the Listing. String True
description Description of the Listing. String False
published Publication status of the listing. Int False

Response

Parameter Description Type
id Unique Listing ID. Int
user_id Unique User ID. Int
title Title of the Listing. String
description Description of the listing. String
published Publication status of the listing. Int

Get a listing


# With shell, you can just pass the correct header with each request

curl "/api/v1/listings/4" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/listings/4', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/listings/4', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/listings/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
  "id": 4,
  "user_id": 2,
  "title": "Grocery list",
  "description": "Stuff i need to buy.",
  "published": 1,
  "created_at": "2019-10-01 10:49:07",
  "updated_at": "2019-10-01 10:49:07",
  "listing_items": [
    {
      "id": 4,
      "listing_id": 2,
      "title": "Buy cheese",
      "deadline": "2019-10-07 13:25:12",
      "done": 0,
      "published": 1,
      "created_at": "2019-10-01 10:49:07",
      "updated_at": "2019-10-01 10:49:07"
    }
  ]
}

/api/v1/listings/{listingId} GET

Response

Parameter Description Type
id Unique Listing ID. Int
user_id Unique User ID. Int
title Title of the Listing. String
description Description of the listing. String
published Publication status of the listing. Int
listing_items Array with all ListingItems that belong to the listing. Array

Update a listing


# With shell, you can just pass the correct header with each request

curl "/api/v1/listings/4" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "title": "New grocery list" }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'title' => 'New grocery list',
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/listings/4', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'title': 'New grocery list' }

requests.put('/api/v1/listings/4', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "title": "New grocery list",
    })
};

fetch("/api/v1/listings/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your update process was successful, your will get a confirmation like that:

{
    "status": true,
    "timestamp": "2019-09-30 14:37:14"
}

/api/v1/listings/{listingId} PUT

Note: Core Developers can update listings for other users.

Request

Parameter Description Type
title Title of the Listing. String
description Description of the Listing. String
published Publication status of the listing. Int

Response

Parameter Description Type

| success | True, if listing was successfully updated. | Bool |

Delete a Listing


# With shell, you can just pass the correct header with each request

curl "/api/v1/listings/4" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/listings/4', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/listings/4', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/listings/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "status": true,
    "timestamp": "2019-09-30 16:51:59"
}

/api/v1/listings/{listingId} DELETE

Response

Parameter Description Type
success True, if listing was successfully deleted. Bool

Listing Items

Listing Items belong to, and can be added to, Listings.

Get all Listing Items

Note: This endpoint will only return the listing items of the requesting user.


# With shell, you can just pass the correct header with each request

curl "/api/v1/listing-items?filter=cheese" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/listing-items?filter=cheese', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/listing?filter=cheese', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/listing-items?filter=cheese", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:


[
    {
        "id": 1,
        "listing_id": 1,
        "title": "Buy cheese",
        "deadline": null,
        "done": 0,
        "published": 1,
        "created_at": "2019-10-01 10:49:07",
        "updated_at": "2019-10-01 10:49:07"
    },
    {/* .. another Listing Item */}
]

/api/v1/listing-items GET

Filter Parameter

Parameter Description Type Required
filter Can be used to filter the response by title. String False

Response

Parameter Description Type
id Unique Listing Item ID. Int
listing_id Unique Listing Item ID. Int
title Title of the Listing Item. String
deadline Deadline of the Listing Item. DateTime String
done Completion status of the Listing Item. Int
published Publication status of the Listing Item. Int

Create a Listing Item


# With shell, you can just pass the correct header with each request

curl "/api/v1/listings" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{
          "title": "Buy cheese",
          "listing_id": 2
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'title' => 'Buy cheese',
        'listing_id' => 2
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/listings', $options);


import json
import requests

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
}

payload = {
    'title': 'Buy cheese',
    'listing_id': 2 
}

requests.post('/api/v1/listings', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "title": "Buy cheese", 
        "listing_id": 2
    })
};

fetch("/api/v1/listings", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 79,
    "title": "Buy cheese",
    "listing_id": 2,
    "done": 0,
    "published": 1,
    "updated_at": "2019-10-01 13:48:04",
    "created_at": "2019-10-01 13:48:04"
 }

/api/v1/listing-items POST

Note: When you pass the listing_id make sure to pass a listing_id of a listing that belongs to you, otherwise the request will not work.

Request

Parameter Description Type Required
title Title of the Listing Item. String True
listing_id Unique Listing Item ID. Int True
deadline Optional deadline of the Listing Item. DateTime String False
done Completion status of the Listing Item. Int False
published Publication status of the Listing Item. Int False

Response

Parameter Description Type
id Unique Listing Item ID. Int
listing_id Unique Listing Item ID. Int
title Title of the Listing Item. String
deadline Deadline of the Listing Item. DateTime String
done Completion status of the Listing Item. Int
published Publication status of the Listing Item. Int

Get a Listing Item


# With shell, you can just pass the correct header with each request

curl "/api/v1/listing-items/4" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/listing-items/4', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/listing-items/4', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/listing-items/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 4,
    "listing_id": 2,
    "title": "Buy more milk",
    "deadline": "2019-10-07 13:25:12",
    "done": 1,
    "published": 1,
    "created_at": "2019-10-01 10:49:07",
    "updated_at": "2019-10-01 10:49:07"
}

/api/v1/listing-items/{listingItemId} GET

Response

Parameter Description Type
id Unique Listing Item ID. Int
listing_id Unique Listing Item ID. Int
title Title of the Listing Item. String
deadline Deadline of the Listing Item. DateTime String
done Completion status of the Listing Item. Int
published Publication status of the Listing Item. Int

Update a Listing Item


# With shell, you can just pass the correct header with each request

curl "/api/v1/listing-items/4" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' \
  -d '{ "title": "Buy more water" }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [
        'title' => 'Buy more water',
    ]
];

$client = new \GuzzleHttp\Client();
$client->put('/api/v1/listing-items/4', $options);


import json
import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'title': 'Buy more water' }

requests.put('/api/v1/listing-items/4', data=json.dumps(payload), headers=headers)


// If you choose to pass your token in your header (recommended)
let options = {
    method: "PUT",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "title": "Buy more water",
    })
};

fetch("/api/v1/listing-items/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your update process was successful, your will get a confirmation like that:

{
    "status": true,
    "timestamp": "2019-09-30 14:37:14"
}

/api/v1/listing-items/{listingItemId} PUT

Note: If you update listing_id make sure to pass a listing_id of a listing that belongs to you, otherwise the request will not work.

Request

Parameter Description Type Required
title Title of the Listing Item. String False
listing_id Unique Listing Item ID. Int False
deadline Optional deadline of the Listing Item. DateTime String False
done Completion status of the Listing Item. Int False
published Publication status of the Listing Item. Int False

Response

Parameter Description Type
success True, if Listing Item was successfully updated. Bool

Delete a Listing Item


# With shell, you can just pass the correct header with each request

curl "/api/v1/listing-items/4" \
  -XDELETE \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->delete('/api/v1/listing-items/4', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.delete('/api/v1/listing-items/4', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "DELETE",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/listing-items/4", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "status": true,
    "timestamp": "2019-09-30 16:51:59"
}

/api/v1/listing-items/{listingItemId} DELETE

Response

Parameter Description Type
success True, if Listing Item was successfully deleted. Bool

Questionnaire

Questionnaires hold sets of questions of a requested service.

Get all questionnaires


# With shell, you can just pass the correct header with each request

curl "/api/v1/questionnaires" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
  -d '{ 
          "gigaaa_service_id": 3,
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [ 
        'gigaaa_service_id' => 3,
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/questionnaires', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = { 'gigaaa_service_id': 3 }

requests.get('/api/v1/questionnaires', data=json.dumps(payload), headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "gigaaa_service_id": 3,
    })
};

fetch("/api/v1/questionnaires", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

[
    {
        "id": 1,
        "title": "This is a questionnaire",
        "description": "Just a questionnaire",
        "gigaaa_service_id": 3,
        "created_at": "2020-02-19 10:15:49",
        "updated_at": "2020-02-19 10:15:49"
    },
    {/* .. another questionnaire */}
]

/api/v1/questionnaires GET

Request

Parameter Description Type Required
gigaaa_service_id Service ID that the questionnaire belongs to. Int True

Response

Parameter Description Type
id Unique questionnaire ID. Int
title Title from the questionnaire String
description Description of the questionnaire. String
gigaaa_service_id The Gigaaa service ID that belong to the questionnaire. Int

Create a questionnaire


# With shell, you can just pass the correct header with each request

curl "/api/v1/questionnaires" \
  -XPOST \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
  -d '{ 
          "title": "Questionnaire from service fifteen",
          "description": "Questions about user experience",
          "gigaaa_service_id": 15,
      }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [ 
        'title'             => 'Questionnaire from service fifteen',
        'description'       => 'Questions about user experience',
        'gigaaa_service_id' => 15,
    ]
];

$client = new \GuzzleHttp\Client();
$client->post('/api/v1/questionnaires', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

payload = {
    'title': 'Questionnaire from service fifteen',
    'description': 'Questions about user experience',
    'gigaaa_service_id': 15,
}

requests.post('/api/v1/questionnaires', data=json.dumps(payload), headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "POST",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
    body: JSON.stringify({
        "title": "Questionnaire from service fifteen",
        "description": "Questions about user experience",
        "gigaaa_service_id": 15,
    })
};

fetch("/api/v1/questionnaires", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "title": "Questionnaire from service fifteen",
    "description": "Questions about user experience",
    "gigaaa_service_id": 15,
    "updated_at": "2020-02-19 10:15:49",
    "created_at": "2020-02-19 10:15:49",
    "id": 1
}

/api/v1/questionnaires POST

Note: You can only make a questionnaire to a service that you organize. Core developer can make questionnaires generally for all services.

Request

Parameter Description Type Required
title Title from the questionnaire String True
gigaaa_service_id The Gigaaa service ID that belong to the questionnaire. Int True
description Description of the questionnaire. String False

Response

Parameter Description Type
title Title from the questionnaire String
description Description of the questionnaire. String
gigaaa_service_id The Gigaaa service ID that belong to the questionnaire. Int
id Unique questionnaire ID. Int

Get a questionnaire


# With shell, you can just pass the correct header with each request

curl "/api/v1/questionnaires/1" \
  -XGET \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ]
];

$client = new \GuzzleHttp\Client();
$client->get('/api/v1/questionnaires/1', $options);


import requests

headers = { 
    'Accept': 'application/json', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx' 
}

requests.get('/api/v1/questionnaires/1', headers=headers)


/* If you choose to pass your token in your header (recommended) */
let options = {
    method: "GET",
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx"
    },
};

fetch("/api/v1/questionnaires/1", options)
    .then((response) => {
        return response.json();
    })
    .catch((error) => {
        console.log(error);
    })

If your token is valid and you have been successfully authenticated, the above command returns JSON structured like this:

{
    "id": 1,
    "title": "This is a questionnaire",
    "description": "Just a questionnaire",
    "gigaaa_service_id": 3,
    "created_at": "2020-02-19 14:29:58",
    "updated_at": "2020-02-19 14:30:49"
}

/api/v1/questionnaires/{questionnaireId} GET

Response

Parameter Description Type
id Unique questionnaire ID. Int
title Title from the questionnaire String
description Description of the questionnaire. String
gigaaa_service_id The Gigaaa service ID that belong to the questionnaire. Int

Update a questionnaire


# With shell, you can just pass the correct header with each request

curl "/api/v1/questionnaires/1" \
  -XPUT \  
  -H 'Accept: application/json' \  
  -H 'Content-Type: application/json' \  
  -H 'Authorization: Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx'
  -d '{ "title": "New questionnaire title" }'

<?php

// If you choose to pass your token in your header (recommended)
$options = [
    'headers' => [
        'Accept'        => 'application/json',
        'Content-Type'  => 'application/json',
        'Authorization' => 'Bearer mXa7NGk9Arxxxxxxxxxxxxxxxxxx',
    ],
    'json' => [ 
        'title' => 'New