Requests and responses

curl -sS -i -X POST "https://api.main-team.org/v1/<organizationId>/application" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 7d2f1c3a-9b8e-4f5a-a1b2-c3d4e5f60718" \
  -d '{"studentId":"<studentId>","examId":"<examId>"}'

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
X-Request-Id: 7d2f1c3a-9b8e-4f5a-a1b2-c3d4e5f60718
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 60

{
  "success": true,
  "message": "Application created successfully.",
  "data": {
    "_id": "66b2c3d4e5f60718293a4b5c",
    "exam": "64a1f0b2c9d8e7f600112233",
    "user": "66a0b1c2d3e4f5061728394a",
    "payment": "66b2c3d4e5f60718293a4b5d",
    "partners": [],
    "participated": false,
    "simulationStarted": false,
    "simulationSubmitted": false,
    "uuid": "a3f-09c-7e1",
    "createdAt": "2026-09-15T08:30:12.345Z",
    "updatedAt": "2026-09-15T08:30:12.345Z"
  }
}

curl -sS -X PUT "https://api.main-team.org/v1/student/<studentId>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","password":"a new password"}'

{
  "error": {
    "code": "bad_request",
    "message": "property password should not exist",
    "documentation_url": "https://hub.main-team.org/api/errors#bad_request",
    "request_id": "0b5c6d0e-8f7a-4b1c-9d2e-3f4a5b6c7d8e"
  }
}

curl -sS "https://api.main-team.org/v1/grade/<gradeId>" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "message": "Grade fetched successfully.",
  "data": {
    "_id": "5f1a2b3c4d5e6f7a8b9c0d1e",
    "name": "10",
    "createdAt": "2020-08-01T09:00:00.000Z",
    "updatedAt": "2020-08-01T09:00:00.000Z"
  }
}

curl -sS "https://api.main-team.org/v1/country?limit=2" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "message": "Countries fetched successfully.",
  "data": [
    {
      "_id": "630e0182c53dc79a6836e67e",
      "name": "GERMANY",
      "iso2": "DE",
      "iso3": "DEU",
      "dialCode": "+49"
    },
    {
      "_id": "630e0182c53dc79a6836e67f",
      "name": "AUSTRIA",
      "iso2": "AT",
      "iso3": "AUT",
      "dialCode": "+43"
    }
  ],
  "pagination": { "page": 1, "limit": 2, "total": 196, "totalPages": 98 }
}

curl -sS "https://api.main-team.org/v1/api-account/validate-me" \
  -H "Authorization: Bearer $TOKEN"

{
  "_id": "665f0c1d2e3a4b5c6d7e8f90",
  "apiKey": "key_Q2x9mT4vLp8sR1nW6yZ3aB7c",
  "companyName": "Northbridge Learning",
  "scopes": [],
  "roles": [
    { "effect": "allow", "action": "*/read", "target": "*" },
    { "effect": "allow", "action": "api/*", "target": "mto" }
  ],
  "isActive": true
}

Content-Disposition: attachment; filename="Ogrenci Sukru.pdf"; filename*=UTF-8''%C3%96%C4%9Frenci%20%C5%9E%C3%BCkr%C3%BC.pdf

curl -sS -o certificate.pdf -w '%{http_code} %{content_type} %{size_download}\n' \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.main-team.org/v1/<organizationId>/certificate/download/<certificateId>"
# 200 application/pdf 184213

import { createWriteStream } from 'node:fs';
import { rename, stat, unlink } from 'node:fs/promises';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';

function fileNameFrom(disposition, fallback) {
  const star = /filename\*=UTF-8''([^;]+)/i.exec(disposition ?? '');
  if (star) return decodeURIComponent(star[1]);
  const plain = /filename="([^"]*)"/i.exec(disposition ?? '');
  return plain ? plain[1] : fallback;
}

export async function downloadCertificate(token, organizationId, certificateId, dir) {
  const res = await fetch(
    `https://api.main-team.org/v1/${organizationId}/certificate/download/${certificateId}`,
    { headers: { Authorization: `Bearer ${token}` } },
  );
  if (!res.ok) {
    const body = await res.json().catch(() => null);
    throw new Error(`${res.status} ${body?.error?.code}: ${body?.error?.message} (${body?.error?.request_id})`);
  }

  // Keep only the last path segment, so a stored name can never leave `dir`.
  const name = fileNameFrom(res.headers.get('content-disposition'), `${certificateId}.pdf`)
    .split(/[\\/]/)
    .pop();
  const partial = `${dir}/${name}.part`;
  try {
    await pipeline(Readable.fromWeb(res.body), createWriteStream(partial));
  } catch (error) {
    await unlink(partial).catch(() => {}); // the connection closed mid-file
    throw error;
  }

  const expected = Number(res.headers.get('content-length') ?? NaN);
  const { size } = await stat(partial);
  if (Number.isFinite(expected) && size !== expected) {
    await unlink(partial);
    throw new Error(`Incomplete download: ${size} of ${expected} bytes`);
  }
  await rename(partial, `${dir}/${name}`);
  return `${dir}/${name}`;
}

<?php
function downloadCertificate(string $token, string $organizationId, string $certificateId, string $dir): string
{
    $headers = [];
    $partial = tempnam($dir, 'dl_');
    $fh = fopen($partial, 'wb');

    $ch = curl_init("https://api.main-team.org/v1/{$organizationId}/certificate/download/{$certificateId}");
    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER => ["Authorization: Bearer {$token}"],
        CURLOPT_FILE => $fh,
        CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$headers) {
            $parts = explode(':', $line, 2);
            if (count($parts) === 2) {
                $headers[strtolower(trim($parts[0]))] = trim($parts[1]);
            }
            return strlen($line);
        },
    ]);
    $ok = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $received = curl_getinfo($ch, CURLINFO_SIZE_DOWNLOAD);
    curl_close($ch);
    fclose($fh);

    if ($ok === false || $status !== 200) {
        $error = json_decode((string) file_get_contents($partial), true)['error'] ?? [];
        unlink($partial);
        throw new RuntimeException("{$status} " . ($error['code'] ?? 'error') . ': ' . ($error['message'] ?? '') . ' (' . ($error['request_id'] ?? '-') . ')');
    }
    if (isset($headers['content-length']) && (int) $headers['content-length'] !== (int) $received) {
        unlink($partial);
        throw new RuntimeException("Incomplete download: {$received} of {$headers['content-length']} bytes");
    }

    $name = "{$certificateId}.pdf";
    $disposition = $headers['content-disposition'] ?? '';
    if (preg_match("/filename\\*=UTF-8''([^;]+)/i", $disposition, $m)) {
        $name = rawurldecode($m[1]);
    } elseif (preg_match('/filename="([^"]*)"/i', $disposition, $m)) {
        $name = $m[1];
    }
    $target = $dir . '/' . basename($name); // basename: never let a stored name leave $dir
    rename($partial, $target);
    return $target;
}

{
  "error": {
    "code": "not_found",
    "message": "Application not found!",
    "documentation_url": "https://hub.main-team.org/api/errors#not_found",
    "request_id": "7d2f1c3a-9b8e-4f5a-a1b2-c3d4e5f60718"
  }
}

import { randomUUID } from 'node:crypto';

const BASE = process.env.MTO_API_BASE ?? 'https://api.main-team.org/v1';

export class ApiError extends Error {
  constructor(status, error, requestId) {
    super(error?.message ?? `HTTP ${status}`);
    this.status = status;
    this.code = error?.code ?? 'unknown';
    this.requestId = error?.request_id ?? requestId;
    this.documentationUrl = error?.documentation_url;
  }
}

export async function api(token, method, path, body) {
  const requestId = randomUUID();
  const res = await fetch(`${BASE}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${token}`,
      'X-Request-Id': requestId,
      ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });

  const text = await res.text();
  let json = null;
  try {
    json = text ? JSON.parse(text) : null;
  } catch {
    // Not JSON: something between you and the API answered. Keep the status.
  }

  if (!res.ok) throw new ApiError(res.status, json?.error, requestId);
  return { status: res.status, body: json, requestId: res.headers.get('x-request-id') };
}

// Usage
const { status, body } = await api(token, 'POST', `/${organizationId}/application`, {
  studentId,
  examId,
});
console.log(status === 201 ? 'created' : 'already existed', body.data._id);

<?php
final class ApiError extends RuntimeException
{
    public function __construct(
        public readonly int $status,
        public readonly string $errorCode,
        string $message,
        public readonly string $requestId,
    ) {
        parent::__construct($message);
    }
}

function api(string $token, string $method, string $path, ?array $body = null): array
{
    $base = getenv('MTO_API_BASE') ?: 'https://api.main-team.org/v1';
    $requestId = bin2hex(random_bytes(16));
    $headers = ["Authorization: Bearer {$token}", "X-Request-Id: {$requestId}"];

    $ch = curl_init($base . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_TIMEOUT => 30,
    ]);
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_THROW_ON_ERROR));
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    $raw = curl_exec($ch);
    if ($raw === false) {
        throw new RuntimeException('Network error: ' . curl_error($ch));
    }
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    $json = json_decode($raw, true);
    if ($status >= 400) {
        $error = $json['error'] ?? [];
        throw new ApiError($status, $error['code'] ?? 'unknown', $error['message'] ?? "HTTP {$status}", $error['request_id'] ?? $requestId);
    }
    return ['status' => $status, 'body' => $json];
}

// Usage
$result = api($token, 'POST', "/{$organizationId}/application", ['studentId' => $studentId, 'examId' => $examId]);
echo ($result['status'] === 201 ? 'created ' : 'already existed ') . $result['body']['data']['_id'];