### Start Gancio with configuration flag

Source: https://gancio.org/install/config

Examples of starting the Gancio service using a specific configuration file path.

```bash
gancio start --config ./config.json
```

```bash
pm2 start gancio start -- --config ~/config.json
```

--------------------------------

### Setup systemd service for Gancio

Source: https://gancio.org/install/debian

Downloads the systemd service file, reloads systemd, and enables the service to start on boot.

```bash
sudo curl https://gancio.org/gancio.service -o /etc/systemd/system/gancio.service
sudo systemctl daemon-reload
sudo systemctl enable gancio
```

--------------------------------

### Install Node.js on Debian

Source: https://gancio.org/install/debian

Installs Node.js 24.x using the NodeSource setup script. Requires curl and sudo. Verify with node -v.

```bash
sudo apt-get install -y curl
sudo curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v
```

--------------------------------

### Start Gancio service

Source: https://gancio.org/install/debian

Starts the Gancio service. It should listen on port 13120.

```bash
sudo systemctl start gancio
```

--------------------------------

### Install Docker, Docker Compose, and nginx

Source: https://gancio.org/install/docker

Installs the required packages for running Gancio with Docker.

```bash
sudo apt install docker docker-compose nginx
```

--------------------------------

### GET /api/session - sample with Python requests

Source: https://gancio.org/operations/get-api-session

Calls the requests library to make a GET request to the session, endpoint. Expects requests module to be installed.

```Python
requests.get("https://demo.gancio.org/api/session")
```

--------------------------------

### Response schema example for GET /api/users

Source: https://gancio.org/operations/get-api-users

Example JSON response for the GET /api/users endpoint. Shows the structure of a user object with fields like id, email, description, is_active, to_notify, role, createdAt, and updatedAt.

```json
[
{
"id": 1,
"email": "example@gancio.org",
"description": "Example user",
"is_active": true,
"to_notify": true,
"role": "user",
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z"
}
]
```

--------------------------------

### Use the template at docs/docker/nominatim

Source: https://gancio.org/install/nominatim

Alternative setup using the template provided in the gancio documentation.

```bash
cd /opt/gancio/docs/docker/nominatim
docker-compose pull
```

--------------------------------

### Enable moderation setting example

Source: https://gancio.org/usage/cli

Example of setting the 'enable_moderation' setting to true. Shows the output and notes that a restart is needed.

```bash
# enable moderation
➜ ./gancio settings set enable_moderation true
enable_report
Old value: false
New value: true

Note that a restart is needed to get the new setting
[settings] ℹ SET 'enable_report' -> 'true'
```

--------------------------------

### Create collection cURL example

Source: https://gancio.org/operations/post-api-collections

Example request using cURL to create a collection.

```bash
curl https://demo.gancio.org/api/collections \
  --request POST \
  --header 'Authorization: Token' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string",
  "isActor": true,
  "isTop": true,
  "sortIndex": 0
}'
```

--------------------------------

### JavaScript request for GET /api/locale/{locale}

Source: https://gancio.org/operations/get-api-locale-%7Blocale%7D

Use fetch to get locale details. The example uses the 'it' locale.

```javascript
fetch('https://demo.gancio.org/api/locale/it')

```

--------------------------------

### Create collection JavaScript example

Source: https://gancio.org/operations/post-api-collections

Example request using the Fetch API in JavaScript.

```javascript
fetch('https://demo.gancio.org/api/collections', {
  method: 'POST',
  headers: {
    Authorization: 'Token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'string',
    isActor: true,
    isTop: true,
    sortIndex: 0
  })
})
```

--------------------------------

### JavaScript sample

Source: https://gancio.org/operations/post-api-ics-import-url

JavaScript fetch example to POST to the endpoint.

```JavaScript
fetch('https://demo.gancio.org/api/ics-import/url', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.org/calendar.ics',
    includePastEvents: false
  })
})
```

--------------------------------

### Copy environment file for Nominatim

Source: https://gancio.org/install/nominatim

Copy the example environment file to .env for configuration.

```bash
cd docs/docker/nominatim/
cp .env.example .env
```

--------------------------------

### cURL Request Example

Source: https://gancio.org/operations/get-api-event-detail-%7Bslug_or_id%7D

Example command to fetch event details using cURL.

```bash
curl https://demo.gancio.org/api/event/detail/1
```

--------------------------------

### cURL request for GET /api/locale/{locale}

Source: https://gancio.org/operations/get-api-locale-%7Blocale%7D

Send a GET request to fetch locale details. Use the example URL with the 'it' locale.

```bash
curl https://demo.gancio.org/api/locale/it

```

--------------------------------

### Create collection Python example

Source: https://gancio.org/operations/post-api-collections

Example request using the Python requests library.

```python
requests.post("https://demo.gancio.org/api/collections",
    headers={
      "Authorization": "Token",
      "Content-Type": "application/json"
    },
    json={
      "name": "string",
      "isActor": True,
      "isTop": True,
      "sortIndex": 0
    }
)
```

--------------------------------

### Python sample

Source: https://gancio.org/operations/post-api-ics-import-url

Python requests example to POST to the endpoint.

```Python
requests.post(
    "https://demo.gancio.org/api/ics-import/url",
    headers={
      "Content-Type": "application/json"
    },
    json={
      "url": "https://example.org/calendar.ics",
      "includePastEvents": False
    }
)
```

--------------------------------

### Move to Gancio installation path

Source: https://gancio.org/install/backup

Navigate to the Gancio installation directory before performing backup or restore operations. The path may vary if you changed the default configuration.

```bash
cd /opt/gancio/ # or where your installation is
```

--------------------------------

### Install Gancio via npm

Source: https://gancio.org/install/debian

Installs the latest Gancio beta package globally using npm. The package is downloaded from https://gancio.org/beta.tgz.

```bash
sudo npm --global add https://gancio.org/beta.tgz
```

--------------------------------

### Get all pages Python requests

Source: https://gancio.org/operations/get-api-pages

Example request using the Python requests library to retrieve all pages.

```python
requests.get("https://demo.gancio.org/api/pages",
    headers={
      "Authorization": "Token"
    }
)
```

--------------------------------

### PHP request for GET /api/locale/{locale}

Source: https://gancio.org/operations/get-api-locale-%7Blocale%7D

Use cURL in PHP to get locale details. The example initializes a cURL session, executes it, and closes it.

```php
$ch = curl_init("https://demo.gancio.org/api/locale/it");

curl_exec($ch);

curl_close($ch);

```

--------------------------------

### cURL Request Example

Source: https://gancio.org/operations/get-api-events-unconfirmed

Example of how to call the endpoint using cURL.

```bash
curl https://demo.gancio.org/api/events/unconfirmed \
  --header 'Authorization: Token'
```

--------------------------------

### JavaScript Fetch Example

Source: https://gancio.org/operations/get-api-events-unconfirmed

Example of how to call the endpoint using the JavaScript fetch API.

```javascript
fetch('https://demo.gancio.org/api/events/unconfirmed', {
  headers: {
    Authorization: 'Token'
  }
})
```

--------------------------------

### Get all pages cURL request

Source: https://gancio.org/operations/get-api-pages

Example request using cURL to retrieve all pages from the Gancio API.

```bash
curl https://demo.gancio.org/api/pages \
  --header 'Authorization: Token'
```

--------------------------------

### PHP cURL Example

Source: https://gancio.org/operations/get-api-events-unconfirmed

Example of how to call the endpoint using PHP.

```php
$ch = curl_init("https://demo.gancio.org/api/events/unconfirmed");

curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Token']);

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### cURL Request Example

Source: https://gancio.org/operations/get-api-events-tag-%7Btag%7D

Example command to retrieve events by tag using cURL.

```bash
curl https://demo.gancio.org/api/events/tag/eventtag
```

--------------------------------

### Get all pages JavaScript fetch request

Source: https://gancio.org/operations/get-api-pages

Example request using the Fetch API in JavaScript to retrieve all pages.

```javascript
fetch('https://demo.gancio.org/api/pages', {
  headers: {
    Authorization: 'Token'
  }
})
```

--------------------------------

### Get current user via Python

Source: https://gancio.org/operations/get-api-user

Example request using the Python requests library to retrieve the current user.

```python
requests.get("https://demo.gancio.org/api/user",
    headers={
      "Authorization": "Token"
    }
)
```

--------------------------------

### Create collection PHP example

Source: https://gancio.org/operations/post-api-collections

Example request using PHP cURL.

```php
$ch = curl_init("https://demo.gancio.org/api/collections");

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Token', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'name' => 'string',
  'isActor' => true,
  'isTop' => true,
  'sortIndex' => 0
]));

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### cURL Login Request

Source: https://gancio.org/operations/post-api-login-token

Example of how to authenticate using the cURL command-line tool.

```bash
curl https://demo.gancio.org/api/login/token \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "admin@gancio.org",
  "password": "password"
}'
```

--------------------------------

### Install dependencies with pnpm

Source: https://gancio.org/dev

Installs project dependencies using pnpm. The documentation notes that yarn, npm, or bun can be used instead, but support is not provided.

```bash
pnpm install
```

--------------------------------

### cURL Request Example

Source: https://gancio.org/operations/put-api-events-%7Bid%7D-assign_to_author

Example cURL command to assign an event to an author.

```bash
curl https://demo.gancio.org/api/events/1/assign_to_author \
  --request PUT \
  --header 'Authorization: Token' \
  --header 'Content-Type: application/json' \
  --data '{
  "userId": 3
}'
```

--------------------------------

### JavaScript Sample for POST /api/ics-import

Source: https://gancio.org/operations/post-api-ics-import

JavaScript fetch example to POST ICS data to the endpoint.

```javascript
fetch('https://demo.gancio.org/api/ics-import', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    icsText: 'BEGIN:VCALENDAR
  VERSION:2.0
  PRODID:-//Example Corp//Example Calendar//EN
  BEGIN:VEVENT
  UID:12345@example.com
  DTSTAMP:20260122T120000Z
  DTSTART:20260125T140000Z
  SUMMARY:Team Meeting
  END:VEVENT
  END:VCALENDAR
  ',
    includePastEvents: false
  })
})
```

--------------------------------

### Python Requests Example

Source: https://gancio.org/operations/get-api-event-detail-%7Bslug_or_id%7D

Example of using the Python requests library to retrieve event details.

```python
requests.get(
    "https://demo.gancio.org/api/event/detail/1"
)
```

--------------------------------

### Python Requests Example

Source: https://gancio.org/operations/get-api-events-unconfirmed

Example of how to call the endpoint using the Python requests library.

```python
requests.get(
    "https://demo.gancio.org/api/events/unconfirmed",
    headers={
      "Authorization": "Token"
    }
)
```

--------------------------------

### JavaScript Fetch Example

Source: https://gancio.org/operations/put-api-events-%7Bid%7D-assign_to_author

Example JavaScript fetch call to assign an event to an author.

```javascript
fetch('https://demo.gancio.org/api/events/1/assign_to_author', {
  method: 'PUT',
  headers: {
    Authorization: 'Token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 3
  })
})
```

--------------------------------

### JavaScript Fetch Example

Source: https://gancio.org/operations/get-api-event-detail-%7Bslug_or_id%7D

Example usage of the fetch API to retrieve event details.

```javascript
fetch('https://demo.gancio.org/api/event/detail/1')
```

--------------------------------

### JavaScript Fetch Example

Source: https://gancio.org/operations/get-api-events-tag-%7Btag%7D

Example usage of the fetch API to retrieve events by tag.

```javascript
fetch('https://demo.gancio.org/api/events/tag/eventtag')
```

--------------------------------

### Start nominatim-docker container

Source: https://gancio.org/install/nominatim

Start the Docker container in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Install Docker dependencies for Nominatim

Source: https://gancio.org/install/nominatim

Install Docker Engine, Docker Compose, and git on Debian.

```bash
sudo apt install docker docker-compose git
```

--------------------------------

### Create user JavaScript fetch request

Source: https://gancio.org/operations/post-api-user

Example JavaScript fetch call to create a user.

```javascript
fetch('https://demo.gancio.org/api/user', {
  method: 'POST',
  headers: {
    Authorization: 'Token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'example@gancio.org',
    description: 'A new user for gancio',
    role: 'user'
  })
})
```

--------------------------------

### Python Requests Example

Source: https://gancio.org/operations/get-api-events-tag-%7Btag%7D

Example usage of the Python requests library to retrieve events by tag.

```python
requests.get(
    "https://demo.gancio.org/api/events/tag/eventtag"
)
```

--------------------------------

### Install Podman and dependencies with apt

Source: https://gancio.org/install/podman

Installs Podman plus uidmap, slirp4netns, fuse-overlayfs, passt, netavark, and aardvark-dns. The page notes nginx is also required as a prerequisite, though it is not part of this command.

```bash
sudo apt install podman uidmap slirp4netns fuse-overlayfs passt netavark aardvark-dns
```

--------------------------------

### Python Sample for POST /api/ics-import

Source: https://gancio.org/operations/post-api-ics-import

Python requests example to POST ICS data to the endpoint.

```python
requests.post("https://demo.gancio.org/api/ics-import",
    headers={
      "Content-Type": "application/json"
    },
    json={
      "icsText": "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//Example Corp//Example Calendar//EN\nBEGIN:VEVENT\nUID:12345@example.com\nDTSTAMP:20260122T120000Z\nDTSTART:20260125T140000Z\nSUMMARY:Team Meeting\nEND:VEVENT\nEND:VCALENDAR\n",
      "includePastEvents": False
    }
)
```

--------------------------------

### Database configuration

Source: https://gancio.org/install/configuration

Configures the database dialect and storage path. The example uses SQLite with storage at /tmp/db.sqlite.

```json
{
  "db": {
    "dialect": "sqlite",
    "storage": "/tmp/db.sqlite"
  }
}
```

--------------------------------

### List all settings

Source: https://gancio.org/usage/cli

Lists all settings in the Gancio instance.

```bash
gancio settings list
```

--------------------------------

### Python request for GET /api/locale/{locale}

Source: https://gancio.org/operations/get-api-locale-%7Blocale%7D

Use requests library to get locale details. The example calls the endpoint with the 'it' locale.

```python
requests.get("https://demo.gancio.org/api/locale/it")

```

--------------------------------

### Set up Gancio Quadlet systemd unit file

Source: https://gancio.org/install/podman

Creates ~/.config/containers/systemd and writes a gancio.container Quadlet unit with the beta image, ./data volume, and published port. The unit configures Restart=always and RestartSec=5.

```bash
mkdir -p ~/.config/containers/systemd
echo '[Unit]
Description=Gancio

[Container]
Image=docker.io/cisti/gancio:beta
Volume=./data:/app/data
PublishPort=127.0.0.1:13120:13120

[Service]
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target default.target' > ~/.config/containers/systemd/gancio.container
```

--------------------------------

### Python Requests Example

Source: https://gancio.org/operations/put-api-events-%7Bid%7D-assign_to_author

Example Python code using the requests library to assign an event to an author.

```python
requests.put(
    "https://demo.gancio.org/api/events/1/assign_to_author",
    headers={
      "Authorization": "Token",
      "Content-Type": "application/json"
    },
    json={
      "userId": 3
    }
)
```

--------------------------------

### Prepare data directory and run Gancio beta container with Podman

Source: https://gancio.org/install/podman

Creates ./data and changes its ownership to UID/GID 1000 using podman unshare, then runs the gancio beta container with ./data mounted at /app/data and bound to 127.0.0.1:13120.

```bash
mkdir -p ./data
podman unshare chown -R 1000:1000 ./data
```

```bash
podman run --name gancio --volume ./data:/app/data -p 127.0.0.1:13120:13120 docker.io/cisti/gancio:beta
```

--------------------------------

### PHP cURL Example

Source: https://gancio.org/operations/get-api-events-tag-%7Btag%7D

Example usage of PHP's cURL library to retrieve events by tag.

```php
$ch = curl_init("https://demo.gancio.org/api/events/tag/eventtag");

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### Accessing the Database

Source: https://gancio.org/dev/plugin

Example of querying the database using the db service.

```typescript
const event = await db.Event.findOne({
  where: {
    title: evt?.title,
    start_datetime: evt?.start_datetime
  }
})
```

--------------------------------

### PHP Sample for POST /api/ics-import

Source: https://gancio.org/operations/post-api-ics-import

PHP cURL example to POST ICS data to the endpoint.

```php
$ch = curl_init("https://demo.gancio.org/api/ics-import");

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'icsText' => 'BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp//Example Calendar//EN
BEGIN:VEVENT
UID:12345@example.com
DTSTAMP:20260122T120000Z
DTSTART:20260125T140000Z
SUMMARY:Team Meeting
END:VEVENT
END:VCALENDAR
',
  'includePastEvents' => false
]));

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### Create user cURL request

Source: https://gancio.org/operations/post-api-user

Example cURL command to create a user.

```bash
curl https://demo.gancio.org/api/user \
  --request POST \
  --header 'Authorization: Token' \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "example@gancio.org",
  "description": "A new user for gancio",
  "role": "user"
}'
```

--------------------------------

### cURL request for collections

Source: https://gancio.org/operations/get-api-collections

Example request using cURL to fetch collections from the demo instance.

```bash
curl https://demo.gancio.org/api/collections
```

--------------------------------

### Python Login Request

Source: https://gancio.org/operations/post-api-login-token

Example of how to authenticate using the Python requests library.

```python
requests.post("https://demo.gancio.org/api/login/token",
    headers={
      "Content-Type": "application/json"
    },
    json={
      "email": "admin@gancio.org",
      "password": "password"
    }
)
```

--------------------------------

### Run the development server

Source: https://gancio.org/dev

Starts the development server for hacking on Gancio. The first user registered from the UI becomes an active administrator.

```bash
pnpm run dev
```

--------------------------------

### GET /api/session - sample with JavaScript fetch

Source: https://gancio.org/operations/get-api-session

Use the fetch API to make a GET request to the /api/session endpoint. The response is a JSON user session.

```JavaScript
fetch('https://demo.gancio.org/api/session')
```

--------------------------------

### Get current user via JavaScript

Source: https://gancio.org/operations/get-api-user

Example request using the fetch API to retrieve the current user.

```javascript
fetch('https://demo.gancio.org/api/user', {
  headers: {
    Authorization: 'Token'
  }
})
```

--------------------------------

### Run Documentation Server

Source: https://gancio.org/dev/code

Command to verify API documentation generation.

```sh
pnpm run docs:dev
```

--------------------------------

### PHP Login Request

Source: https://gancio.org/operations/post-api-login-token

Example of how to authenticate using PHP's cURL extension.

```php
$ch = curl_init("https://demo.gancio.org/api/login/token");

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'email' => 'admin@gancio.org',
  'password' => 'password'
]));

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### Get instances with PHP

Source: https://gancio.org/operations/get-api-instances

Retrieves instance data using PHP's cURL library.

```php
$ch = curl_init("https://demo.gancio.org/api/instances");

curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Token']);

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### Run Gancio Docker container

Source: https://gancio.org/install/docker

Starts the Gancio container, mapping port 13120 and mounting the data directory and .env.example file.

```bash
docker run --rm  -p 13120:13120 -v ./data:/app/data -v ./.env.example:/app/.env cisti/gancio:beta
```

--------------------------------

### Get current user via cURL

Source: https://gancio.org/operations/get-api-user

Example request using cURL to fetch the current user with an Authorization header.

```bash
curl https://demo.gancio.org/api/user \
  --header 'Authorization: Token'
```

--------------------------------

### JavaScript fetch sample for POST /api/user/register

Source: https://gancio.org/operations/post-api-user-register

JavaScript fetch example to register a user. Uses POST method with JSON headers and body.

```javascript
fetch('https://demo.gancio.org/api/user/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'example@gancio.org',
    password: 'MY_PASSWORD',
    description: 'A new user for gancio'
  })
})
```

--------------------------------

### Get all pages PHP cURL request

Source: https://gancio.org/operations/get-api-pages

Example request using PHP's cURL library to retrieve all pages.

```php
$ch = curl_init("https://demo.gancio.org/api/pages");

curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Token']);

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### Get instances with Python

Source: https://gancio.org/operations/get-api-instances

Retrieves instance data using the Python requests library.

```python
requests.get("https://demo.gancio.org/api/instances",
    headers={
      "Authorization": "Token"
    }
)
```

--------------------------------

### Get collection filters Python requests

Source: https://gancio.org/operations/get-api-collections-filters-%7Bcollection_id%7D

Example request using the Python requests library to retrieve collection filters.

```python
requests.get(
    "https://demo.gancio.org/api/collections/filters/2"
)
```

--------------------------------

### JavaScript fetch sample for PUT /api/settings

Source: https://gancio.org/operations/put-api-settings

JavaScript fetch example to set a setting value. Uses bearer token and JSON body.

```javascript
fetch('https://demo.gancio.org/api/settings', {
  method: 'PUT',
  headers: {
    Authorization: 'Token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    key: 'title',
    value: 'Demo Gancio'
  })
})
```

--------------------------------

### Get collection filters JavaScript fetch

Source: https://gancio.org/operations/get-api-collections-filters-%7Bcollection_id%7D

Example request using the JavaScript fetch API to retrieve collection filters.

```javascript
fetch('https://demo.gancio.org/api/collections/filters/2')
```

--------------------------------

### Get instances with JavaScript

Source: https://gancio.org/operations/get-api-instances

Retrieves instance data using the fetch API in JavaScript.

```javascript
fetch('https://demo.gancio.org/api/instances', {
  headers: {
    Authorization: 'Token'
  }
})
```

--------------------------------

### Get collection filters cURL request

Source: https://gancio.org/operations/get-api-collections-filters-%7Bcollection_id%7D

Example request using cURL to fetch filters for collection ID 2.

```bash
curl https://demo.gancio.org/api/collections/filters/2
```

--------------------------------

### GET /api/session - sample with cURL

Source: https://gancio.org/operations/get-api-session

Make a GET request to the base path to retrieve current user information. If session is valid, returns user object; if session invalid, may return 204 or other response. This is the simpler of samples.

```cURL
curl https://demo.gancio.org/api/session
```

--------------------------------

### Enable a user

Source: https://gancio.org/usage/cli

Enables a user account.

```bash
gancio users enable <email>
```

--------------------------------

### Get instances with cURL

Source: https://gancio.org/operations/get-api-instances

Retrieves instance data using the cURL command-line tool with a bearer token.

```bash
curl https://demo.gancio.org/api/instances \
  --header 'Authorization: Token'
```

--------------------------------

### Get collection filters PHP cURL

Source: https://gancio.org/operations/get-api-collections-filters-%7Bcollection_id%7D

Example request using PHP's cURL library to retrieve collection filters.

```php
$ch = curl_init("https://demo.gancio.org/api/collections/filters/2");

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### Automatic backup with Restic for Gancio (NixOS)

Source: https://gancio.org/install/nixos

Configures a Restic backup job for Gancio, running as the 'gancio' user. It initializes the repository, uses rclone with a Nextcloud remote, and includes a backupPrepareCommand that dumps the PostgreSQL database before backup. The paths include /var/lib/gancio and prune options keep daily, weekly, and monthly snapshots.

```nix
{
  pkgs,
  ...
}: {
  services.restic.backups.gancio = {
    user = "gancio";
    initialize = true;
    repository = "rclone:nextcloud:gancio";
    rcloneConfigFile = /path/to/rclone.config;
    passwordFile = /path/to/restic-backup-password;
    paths = [
      "/var/lib/gancio"
    ];
    backupPrepareCommand = ''
      cd /var/lib/gancio
      ${pkgs.postgresql}/bin/pg_dump -Fc gancio > gancio-db.dump
    '';
    pruneOpts = [
      "--keep-daily 3"
      "--keep-weekly 1"
      "--keep-monthly 1"
    ];
  };
}
```

```ini
[nextcloud]
type = webdav
url = https://nexcloud.example.com/remote.php/dav/files/gancio-backup
vendor = nextcloud
user = gancio-backup
pass = xxxxx
```

--------------------------------

### cURL request to GET /api/events/{id}

Source: https://gancio.org/operations/get-api-events-%7Bid%7D

Fetches an event by its ID using cURL. The example uses the demo instance URL.

```bash
curl https://demo.gancio.org/api/events/1
```

--------------------------------

### cURL Request for Plugin Route

Source: https://gancio.org/operations/get-api-plugins-%7Bname%7D-%7Bpath%7D

Example request using cURL to retrieve a plugin route.

```bash
curl 'https://demo.gancio.org/api/plugins/Example/{path}'
```

--------------------------------

### GET /api/resources/list - 200 Response JSON

Source: https://gancio.org/operations/get-api-resources-list

Example response body for the GET /api/resources/list endpoint. Shows the structure of a filtered resource list, including nested event, user, place, and tag objects. The response includes pagination metadata: count and totalPages.

```json
{
"data": [
{
"activitypub_id": "AP_ID",
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z",
"hidden": false,
"data": {
},
"apUserApId": "AP_USER_ID",
"APUser": {
"ap_id": "AP_USER_ID",
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z",
"follower": false,
"following": false,
"trusted": false,
"blocked": false,
"object": {
},
"instanceDomain": "string",
"instance": {
"domain": "instance_domain.org",
"name": "Instance Name",
"blocked": false,
"data": "string",
"applicationActor": "string",
"APUsers": [
{
}
]
},
"events": [
{
"id": 1,
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z",
"title": "Event title",
"status": "EventScheduled",
"slug": "event-slug",
"start_datetime": 1784109600,
"end_datetime": 1784131200,
"media": [
{
"name": "Image name",
"url": "6e599b27-5ed8-44c9-b954-53e9c6fa3c80.jpg",
"height": 400,
"width": 200,
"size": 50000,
"focalpoint": [
[
0,
0
]
]
}
],
"description": "Event description",
"is_visible": true,
"online_locations": [
[
"https://event.online",
"https://eventalt.online"
]
],
"recurrent": {
"frequency": "1w",
"type": "ordinal"
},
"ld_signature": {
"@context": "https://w3id.org/identity/v1",
"creator": "http://localhost:13120/federation/u/relay#main-key",
"created": "2026-07-01T21:07:49.103Z",
"signatureValue": "SIGNATURE_KEY"
},
"ap_object": {
},
"likes": [
{
}
],
"boost": [
{
}
],
"ap_id": "AP_ID",
"userId": 3,
"user": {
"id": 1,
"email": "example@gancio.org",
"description": "Example user",
"is_active": true,
"to_notify": true,
"role": "user",
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z"
},
"parentId": 23,
"parent": "[Circular Reference]",
"children": [
{
}
],
"placeId": 23,
"place": {
"id": 20,
"name": "Location name",
"address": "Address",
"ap_id": "AP_ID",
"postal_address": {
},
"latitude": 40.5574,
"longitude": 8.3263,
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z"
},
"tags": [
{
"tag": "event_tag",
"normalizedTag": "event_tag",
"events": [
{
}
]
}
],
"apUserApId": "AP_USER_ID",
"apUser": "[Circular Reference]",
"messages": [
{
"id": 12,
"message": "A message for an event.",
"author": "AUTHOR",
"is_author_visible": true,
"eventId": 3,
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z"
}
],
"resources": [
{
}
]
}
],
"resources": [
{
}
]
},
"eventId": 2,
"event": {
"id": 1,
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z",
"title": "Event title",
"status": "EventScheduled",
"slug": "event-slug",
"start_datetime": 1784109600,
"end_datetime": 1784131200,
"media": [
{
"name": "Image name",
"url": "6e599b27-5ed8-44c9-b954-53e9c6fa3c80.jpg",
"height": 400,
"width": 200,
"size": 50000,
"focalpoint": [
[
0,
0
]
]
}
],
"description": "Event description",
"is_visible": true,
"online_locations": [
[
"https://event.online",
"https://eventalt.online"
]
],
"recurrent": {
"frequency": "1w",
"type": "ordinal"
},
"ld_signature": {
"@context": "https://w3id.org/identity/v1",
"creator": "http://localhost:13120/federation/u/relay#main-key",
"created": "2026-07-01T21:07:49.103Z",
"signatureValue": "SIGNATURE_KEY"
},
"ap_object": {
},
"likes": [
{
}
],
"boost": [
{
}
],
"ap_id": "AP_ID",
"userId": 3,
"user": {
"id": 1,
"email": "example@gancio.org",
"description": "Example user",
"is_active": true,
"to_notify": true,
"role": "user",
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z"
},
"parentId": 23,
"parent": "[Circular Reference]",
"children": [
{
}
],
"placeId": 23,
"place": {
"id": 20,
"name": "Location name",
"address": "Address",
"ap_id": "AP_ID",
"postal_address": {
},
"latitude": 40.5574,
"longitude": 8.3263,
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z"
},
"tags": [
{
"tag": "event_tag",
"normalizedTag": "event_tag",
"events": [
{
}
]
}
],
"apUserApId": "AP_USER_ID",
"apUser": "[Circular Reference]",
"messages": [
{
"id": 12,
"message": "A message for an event.",
"author": "AUTHOR",
"is_author_visible": true,
"eventId": 3,
"createdAt": "2020-01-29T18:10:16.630Z",
"updatedAt": "2020-01-30T22:42:14.789Z"
}
],
"resources": [
{
}
]
}
}
],
"count": 34,
"totalPages": 4
}
```

--------------------------------

### Get API Settings with cURL

Source: https://gancio.org/operations/get-api-settings

Retrieve settings using the cURL command-line tool.

```bash
curl https://demo.gancio.org/api/settings
```

--------------------------------

### PHP cURL request to GET /api/events/{id}

Source: https://gancio.org/operations/get-api-events-%7Bid%7D

Fetches an event by its ID using PHP's cURL functions. The example initializes a cURL session, executes it, and closes it.

```php
$ch = curl_init("https://demo.gancio.org/api/events/1");

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### JavaScript fetch sample for POST /api/announcements

Source: https://gancio.org/operations/post-api-announcements

JavaScript fetch example to create an announcement. Uses bearer token and JSON body.

```javascript
fetch('https://demo.gancio.org/api/announcements', {
  method: 'POST',
  headers: {
    Authorization: 'Token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Announcement title',
    announcement: 'Announcement text',
    visible: true
  })
})
```

--------------------------------

### Get API Settings with JavaScript

Source: https://gancio.org/operations/get-api-settings

Retrieve settings using the Fetch API in JavaScript.

```javascript
fetch('https://demo.gancio.org/api/settings')
```

--------------------------------

### JavaScript fetch request for collections

Source: https://gancio.org/operations/get-api-collections

Example request using the Fetch API to retrieve collections.

```javascript
fetch('https://demo.gancio.org/api/collections')
```

--------------------------------

### JavaScript fetch sample for POST /api/events/messages/{event_id}

Source: https://gancio.org/operations/post-api-events-messages-%7Bevent_id%7D

JavaScript fetch example to create a message. Sends a POST request with JSON body.

```javascript
fetch('https://demo.gancio.org/api/events/messages/1', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Message for the event',
    is_author_visible: true
  })
})
```

--------------------------------

### Create user Python requests call

Source: https://gancio.org/operations/post-api-user

Example Python request using the requests library to create a user.

```python
requests.post("https://demo.gancio.org/api/user",
    headers={
      "Authorization": "Token",
      "Content-Type": "application/json"
    },
    json={
      "email": "example@gancio.org",
      "description": "A new user for gancio",
      "role": "user"
    }
)
```

--------------------------------

### Create user PHP cURL request

Source: https://gancio.org/operations/post-api-user

Example PHP implementation using cURL to create a user.

```php
$ch = curl_init("https://demo.gancio.org/api/user");

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Token', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'email' => 'example@gancio.org',
  'description' => 'A new user for gancio',
  'role' => 'user'
]));

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### Archive database, configuration, and data files

Source: https://gancio.org/install/backup

Creates a timestamped tar.gz archive of the database dump, configuration, custom user locales, logs, custom plugins, images, and thumbnails. The command lists existing files from a set of possible paths.

```bash
sudo tar -czf gancio-$(date +%Y-%m-%d-%H%M%S)-backup.tgz  \
  $(ls -d config.json uploads user_locale gancio.sqlite db.sqlite gancio.dump postgres data db logs 2> /dev/null)
```

--------------------------------

### Run database migration

Source: https://gancio.org/usage/cli

Executes the database migration command for Gancio.

```bash
gancio migrate
```

--------------------------------

### Configure database settings

Source: https://gancio.org/install/config

Sets the database dialect and storage path.

```json
  "db": {
    "dialect": "sqlite",
    "storage": "/tmp/db.sqlite"
  }
```

--------------------------------

### Response JSON for POST /api/user/register

Source: https://gancio.org/operations/post-api-user-register

Example response after successful registration. Contains user details including id, email, description, is_active, to_notify, role, and timestamps.

```json
{
  "id": 1,
  "email": "example@gancio.org",
  "description": "Example user",
  "is_active": true,
  "to_notify": true,
  "role": "user",
  "createdAt": "2020-01-29T18:10:16.630Z",
  "updatedAt": "2020-01-30T22:42:14.789Z"
}
```

--------------------------------

### List all users

Source: https://gancio.org/usage/cli

Lists all users in the Gancio instance.

```bash
gancio users list
```

--------------------------------

### PHP cURL Example

Source: https://gancio.org/operations/put-api-events-%7Bid%7D-assign_to_author

Example PHP code using cURL to assign an event to an author.

```php
$ch = curl_init("https://demo.gancio.org/api/events/1/assign_to_author");

curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Token', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'userId' => 3
]));

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### PHP cURL sample for POST /api/user/register

Source: https://gancio.org/operations/post-api-user-register

PHP cURL example to register a user. Initializes a cURL session, sets POST options, and executes the request.

```php
$ch = curl_init("https://demo.gancio.org/api/user/register");

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'email' => 'example@gancio.org',
  'password' => 'MY_PASSWORD',
  'description' => 'A new user for gancio'
]));

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### JavaScript fetch example to update plugin settings

Source: https://gancio.org/operations/put-api-plugins-%7Bname%7D-settings

JavaScript fetch call to the settings endpoint with PUT method and headers for bearer token and JSON content type.

```javascript
fetch('https://demo.gancio.org/api/plugins/Example/settings', {
  method: 'PUT',
  headers: {
    Authorization: 'Token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    enable: false,
    setting_key: 'setting_value'
  })
})
```

--------------------------------

### Create Gancio directory

Source: https://gancio.org/install/docker

Creates and changes into the directory where Gancio data and configuration will be stored.

```bash
mkdir -p /opt/gancio
cd /opt/gancio
```

--------------------------------

### PHP cURL Example

Source: https://gancio.org/operations/get-api-event-detail-%7Bslug_or_id%7D

Example of using PHP's cURL library to perform the request.

```php
$ch = curl_init("https://demo.gancio.org/api/event/detail/1");

curl_exec($ch);

curl_close($ch);
```

--------------------------------

### Create page with JavaScript fetch

Source: https://gancio.org/operations/post-api-pages

JavaScript fetch example to create a page. Uses POST method with JSON body.

```javascript
fetch('https://demo.gancio.org/api/pages', {
  method: 'POST',
  headers: {
    Authorization: 'Token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'More info',
    content: 'More info about Gancio.',
    visible: true
  })
})
```

--------------------------------

### Create an admin user with --role flag

Source: https://gancio.org/usage/cli

Creates a user with administrator privileges using the --role flag.

```bash
gancio users create admin@example.com --role admin
```

--------------------------------

### Create OAuth2 Client via POST /api/client

Source: https://gancio.org/dev/oauth

Registers a new application to obtain OAuth2 credentials. The request requires a client name, redirect URI, and website URL.

```bash
curl -X POST \
        -d 'client_name=Wordpress Event Manager' \
        -d 'redirect_uris=https://noblogs.org/' \
        -d 'website=https://myapp.example' \
        http://localhost:13120/api/client
```

--------------------------------

### Create page response (JSON)

Source: https://gancio.org/operations/post-api-pages

Example response for a successful page creation. Includes id, slug, and timestamps.

```json
{
  "id": 3,
  "title": "More info",
  "content": "More info about Gancio.",
  "visible": true,
  "slug": "more-info",
  "createdAt": "2020-01-29T18:10:16.630Z",
  "updatedAt": "2020-01-30T22:42:14.789Z"
}
```

--------------------------------

### Reannounce event by id - API samples (cURL, JavaScript, PHP, Python)

Source: https://gancio.org/operations/put-api-events-%7Bid%7D-reannounce

Samples for the PUT /api/events/{id}/reannounce endpoint, shown in the API documentation's Samples tab. Each example sends a PUT request to reannounce event id 1, using a bearer token in the Authorization header. The cURL example uses the --request PUT flag; the JavaScript example uses fetch with method PUT; the PHP example uses curl_init and curl_setopt; the Python example uses requests.put.

```bash
curl https://demo.gancio.org/api/events/1/reannounce \
  --request PUT \
  --header 'Authorization: Token'
```

```javascript
fetch('https://demo.gancio.org/api/events/1/reannounce', {
  method: 'PUT',
  headers: {
    Authorization: 'Token'
  }
})
```

```php
$ch = curl_init("https://demo.gancio.org/api/events/1/reannounce");

curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Token']);

curl_exec($ch);

curl_close($ch);
```

```python
requests.put(
    "https://demo.gancio.org/api/events/1/reannounce",
    headers={
      "Authorization": "Token"
    }
)
```

--------------------------------

### Python requests to get collection events

Source: https://gancio.org/operations/get-api-collections-%7Bid%7D

Uses the requests library to perform a GET request to the collection endpoint.

```Python
requests.get(
    "https://demo.gancio.org/api/collections/collection_test"
)
```

--------------------------------

### Serve Raw File

Source: https://gancio.org/dev/code

Use the serveFile helper to send files from the server.

```ts
return serveFile(event, filePath)
```

--------------------------------

### Python requests sample for POST /api/announcements

Source: https://gancio.org/operations/post-api-announcements

Python requests example to create an announcement. Uses bearer token and JSON body.

```python
requests.post(
    "https://demo.gancio.org/api/announcements",
    headers={
      "Authorization": "Token",
      "Content-Type": "application/json"
    },
    json={
      "title": "Announcement title",
      "announcement": "Announcement text",
      "visible": True
    }
)
```

--------------------------------

### Python requests sample for PUT /api/settings

Source: https://gancio.org/operations/put-api-settings

Python requests example to set a setting value. Uses bearer token and JSON body.

```python
requests.put("https://demo.gancio.org/api/settings",
    headers={
      "Authorization": "Token",
      "Content-Type": "application/json"
    },
    json={
      "key": "title",
      "value": "Demo Gancio"
    }
)
```

--------------------------------

### Python requests call to GET /api/announcements

Source: https://gancio.org/operations/get-api-announcements

Sends a GET request using the requests library to retrieve visible announcements.

```Python
requests.get(
    "https://demo.gancio.org/api/announcements"
)
```

--------------------------------

### cURL request for GET /api/users

Source: https://gancio.org/operations/get-api-users

Sample cURL command to call the GET /api/users endpoint. Requires a bearer token for authorization.

```bash
curl https://demo.gancio.org/api/users \
  --header 'Authorization: Token'
```

--------------------------------

### GET /api/resources/list/{id} with Python

Source: https://gancio.org/operations/get-api-resources-list-%7Bid%7D

Fetch event resources using the requests library in Python. Sends a GET request to the endpoint.

```python
requests.get(
    "https://demo.gancio.org/api/resources/list/4"
)
```

--------------------------------

### cURL request to get event messages

Source: https://gancio.org/operations/get-api-events-messages-%7Bevent_id%7D

Uses cURL to send a GET request to the endpoint. The event_id is set to 1 in the URL.

```cURL
curl https://demo.gancio.org/api/events/messages/1
```

--------------------------------

### Extract backup archive

Source: https://gancio.org/install/backup

Extracts the backup archive created by the backup process. Use this after installing a clean Gancio and moving to the installation path.

```bash
tar xvf gancio-*-backup.tgz
```

--------------------------------

### React to events - onEventCreate, onEventUpdate, onEventDelete

Source: https://gancio.org/dev/plugins

Plugins can react to event related actions. The example shows handlers for create, update, and delete events, using plugin.gancio.settings.baseurl to build event links.

```javascript
  onEventCreate (event) {
    const eventLink = `${plugin.gancio.settings.baseurl}/event/${event.slug}`
    if (!event.is_visible) {
      console.error(`Unconfirmed event created: ${event.title} / ${eventLink}`)
    } else {
      console.error(`Event created: ${event.title} / ${eventLink}`)
    }
  },

  onEventUpdate (event) {
    console.error(`Event "${event.title}" updated`)
  },

  onEventDelete (event) {
    console.error(`Event "${event.title}" deleted`)
  }
```

--------------------------------

### Python requests to get event messages

Source: https://gancio.org/operations/get-api-events-messages-%7Bevent_id%7D

Uses the requests library to send a GET request to the endpoint. The event_id is set to 1 in the URL.

```Python
requests.get(
    "https://demo.gancio.org/api/events/messages/1"
)
```

--------------------------------

### Load method for plugin initialization

Source: https://gancio.org/dev/plugins

When a plugin is enabled by an administrator, Gancio calls the load method if specified. It receives an object with gancio_settings, db, helpers, log, and the plugin's local settings. Access to DB is available since 1.6.14.

```javascript
load ({ settings: gancio_settings, db, helpers, log}, settings) {

  // access to your plugin local settings
  console.info('Your local settings are in ', settings)
  console.info(`For example, you can access to your default language setting by using ${settings.my_default_language}`)

  // access to gancio settings
  console.info(`Gancio settings are in ${gancio_settings}, e.g. ${gancio.settings.baseurl}`)

  // log something
  log.warn('This is a log entry from my example plugin')

  // use the DB (since 1.6.14)
  console.info(db.models.findAll())
  console.info(db.query('CREATE TABLE IF NOT EXISTS myPluginTable'))
}
```