api.drop.m7.org Endpoint Documentation

Generated on 2026-07-19 from cli/endpoints.php --json, config/general.json, and the PHP handlers under lib/php/thisProject/api.

Conventions

• Base URL: https://api.drop.m7.org
• Response format: json; error format: json.
• Request parameters are read from the parsed request payload ($this->r), which may include query, form, or JSON body values depending on the router parser.
• ANY means the route is registered without an HTTP-method constraint. Prefer POST for mutations and request bodies unless the caller contract says otherwise.
• "Detected request fields" are statically extracted from handlers and delegated service methods; table-backed filters may accept additional fields.

Authentication

• M7 token config: check soft, issuer id.m7.org; allowed algorithms RS512.
• Principal route protection from config:
  • /v1/drop -> user, admin, root
  • /v1/admin -> admin, root

Endpoint Summary

Method	Path	Auth	Handler
ANY	/hello	no explicit auth gate detected in route/handler	hello\Controller
POST	/v1/admin/cleanup	principal route rule: admin, root	admin\Cleanup
POST	/v1/admin/get	principal route rule: admin, root	admin\Get
POST	/v1/admin/list	principal route rule: admin, root	admin\ListItems
POST	/v1/consume	public consume path; anonymous drops need no principal, private drops require owner principal	Consume
POST	/v1/drop/activate	principal route rule: user, admin, root	drop\Activate
POST	/v1/drop/consume	principal route rule: user, admin, root	drop\Consume
POST	/v1/drop/delete	principal route rule: user, admin, root	drop\Delete
POST	/v1/drop/get	principal route rule: user, admin, root	drop\Get
POST	/v1/drop/list	principal route rule: user, admin, root	drop\ListItems
POST	/v1/drop/reserve	principal route rule: user, admin, root	drop\Reserve
POST	/v1/drop/revoke	principal route rule: user, admin, root	drop\Revoke
POST	/v1/drop/status	principal route rule: user, admin, root	drop\Status
POST	/v1/drop/store	principal route rule: user, admin, root	drop\Store

Endpoints

ANY /hello

Handles hello.

• Handler: thisProject\api\hello\Controller
• Source: lib/php/thisProject/api/hello/Controller.php
• Auth: no explicit auth gate detected in route/handler
• Detected request fields: none in the handler; endpoint may be informational or delegates opaque input.
• Response: success comment(s): OK.

POST /v1/admin/cleanup

Cleans up cleanup.

• Handler: thisProject\api\admin\Cleanup
• Source: lib/php/thisProject/api/admin/Cleanup.php
• Delegates to: lib/php/thisProject/service/Drop.php::cleanup
• Auth: principal route rule: admin, root
• Detected request fields:
  • id (optional/detected). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
• Response: success comment(s): OK; data key(s): deleted_count, scanned_count.

POST /v1/admin/get

Gets get.

• Handler: thisProject\api\admin\Get
• Source: lib/php/thisProject/api/admin/Get.php
• Delegates to: lib/php/thisProject/service/Drop.php::getAdmin
• Auth: principal route rule: admin, root
• Detected request fields:
  • id (required). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
  • key (required). Key id/name or drop encryption key depending on the endpoint. Default: ''.
  • payload (optional/detected). Payload to store or encrypt. Default: ''.
  • payload_format (optional/detected). Payload format such as json, text, html, or base64. Default: 'json'.
  • status (optional/detected). Status filter or value. Default: ''.
• Response: success comment(s): OK.
• Notable errors: Drop not found; Missing key; Drop has expired; Drop is not active; Invalid.

POST /v1/admin/list

Lists list items.

• Handler: thisProject\api\admin\ListItems
• Source: lib/php/thisProject/api/admin/ListItems.php
• Delegates to: lib/php/thisProject/service/Drop.php::listAdmin
• Auth: principal route rule: admin, root
• Detected request fields: none in the handler; endpoint may be informational or delegates opaque input.
• Response: success comment(s): OK.

POST /v1/consume

Consumes consume.

• Handler: thisProject\api\Consume
• Source: lib/php/thisProject/api/Consume.php
• Delegates to: lib/php/thisProject/service/Drop.php::publicConsume
• Auth: public consume path; anonymous drops can be consumed without a principal, while non-anonymous drops require the current principal to match the drop owner.
• Detected request fields:
  • id (required). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
  • key (required). Key id/name or drop encryption key depending on the endpoint. Default: ''.
  • anonymous (optional/detected). Whether the resource can be consumed anonymously. Default: false.
  • payload (optional/detected). Payload to store or encrypt. Default: ''.
  • payload_format (optional/detected). Payload format such as json, text, html, or base64. Default: 'json'.
  • status (optional/detected). Status filter or value. Default: ''.
• Response: success comment(s): OK.
• Notable errors: Owner access required for this drop; Missing key; Drop not found; Drop has expired; Drop is not active; Principal id is unavailable; Invalid.

POST /v1/drop/activate

Activates drop.

• Handler: thisProject\api\drop\Activate
• Source: lib/php/thisProject/api/drop/Activate.php
• Delegates to: lib/php/thisProject/service/Drop.php::activate
• Auth: principal route rule: user, admin, root
• Detected request fields:
  • data (required). Payload/data value. Default: null.
  • id (required). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
  • payload (required). Payload to store or encrypt. Default: null.
  • anonymous (optional/detected). Whether the resource can be consumed anonymously.
  • content_type (optional/detected). MIME content type override. Default: null.
  • expires (optional/detected). Expiration timestamp.
  • expires_at (optional/detected). Expiration timestamp.
  • key (optional/detected). Key id/name or drop encryption key depending on the endpoint. Default: ''.
  • kind (optional/detected). Type/kind discriminator.
  • metadata (optional/detected). Caller-supplied metadata object.
  • payload_format (optional/detected). Payload format such as json, text, html, or base64. Default: ''.
  • status (optional/detected). Status filter or value. Default: ''.
  • ttl (optional/detected). Time-to-live in seconds. Default: ''.
• Response: success comment(s): OK.
• Notable errors: Drop has expired; Only reserved drops may be activated; Principal id is unavailable; Drop not found; Missing payload; Invalid payload_format; Invalid ttl; Invalid.

POST /v1/drop/consume

Consumes drop.

• Handler: thisProject\api\drop\Consume
• Source: lib/php/thisProject/api/drop/Consume.php
• Delegates to: lib/php/thisProject/service/Drop.php::consume
• Auth: principal route rule: user, admin, root
• Detected request fields:
  • id (required). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
  • key (required). Key id/name or drop encryption key depending on the endpoint. Default: ''.
  • payload (optional/detected). Payload to store or encrypt. Default: ''.
  • payload_format (optional/detected). Payload format such as json, text, html, or base64. Default: 'json'.
  • status (optional/detected). Status filter or value. Default: ''.
• Response: success comment(s): OK.
• Notable errors: Principal id is unavailable; Missing key; Drop not found; Drop has expired; Drop is not active; Invalid.

POST /v1/drop/delete

Deletes drop.

• Handler: thisProject\api\drop\Delete
• Source: lib/php/thisProject/api/drop/Delete.php
• Delegates to: lib/php/thisProject/service/Drop.php::delete
• Auth: principal route rule: user, admin, root
• Detected request fields:
  • id (required). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
• Response: success comment(s): OK; data key(s): id, deleted.
• Notable errors: Drop not found; Principal id is unavailable; Invalid.

POST /v1/drop/get

Gets drop.

• Handler: thisProject\api\drop\Get
• Source: lib/php/thisProject/api/drop/Get.php
• Delegates to: lib/php/thisProject/service/Drop.php::get
• Auth: principal route rule: user, admin, root
• Detected request fields:
  • id (required). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
  • key (required). Key id/name or drop encryption key depending on the endpoint. Default: ''.
  • payload (optional/detected). Payload to store or encrypt. Default: ''.
  • payload_format (optional/detected). Payload format such as json, text, html, or base64. Default: 'json'.
  • status (optional/detected). Status filter or value. Default: ''.
• Response: success comment(s): OK.
• Notable errors: Principal id is unavailable; Drop not found; Missing key; Drop has expired; Drop is not active; Invalid.

POST /v1/drop/list

Lists drop.

• Handler: thisProject\api\drop\ListItems
• Source: lib/php/thisProject/api/drop/ListItems.php
• Delegates to: lib/php/thisProject/service/Drop.php::listOwn
• Auth: principal route rule: user, admin, root
• Detected request fields: none in the handler; endpoint may be informational or delegates opaque input.
• Response: success comment(s): OK.
• Notable errors: Principal id is unavailable.

POST /v1/drop/reserve

Reserves drop.

• Handler: thisProject\api\drop\Reserve
• Source: lib/php/thisProject/api/drop/Reserve.php
• Delegates to: lib/php/thisProject/service/Drop.php::reserve
• Auth: principal route rule: user, admin, root
• Detected request fields:
  • anonymous (optional/detected). Whether the resource can be consumed anonymously. Default: false.
  • expires (optional/detected). Expiration timestamp.
  • expires_at (optional/detected). Expiration timestamp.
  • id (optional/detected). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
  • kind (optional/detected). Type/kind discriminator. Default: null.
  • metadata (optional/detected). Caller-supplied metadata object. Default: null.
  • ttl (optional/detected). Time-to-live in seconds. Default: ''.
• Response: success comment(s): OK.
• Notable errors: Drop id already exists; Principal id is unavailable; Invalid ttl; Invalid; expires_at must be in the future.

POST /v1/drop/revoke

Revokes drop.

• Handler: thisProject\api\drop\Revoke
• Source: lib/php/thisProject/api/drop/Revoke.php
• Delegates to: lib/php/thisProject/service/Drop.php::revoke
• Auth: principal route rule: user, admin, root
• Detected request fields:
  • id (required). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
  • expires (optional/detected). Expiration timestamp.
  • expires_at (optional/detected). Expiration timestamp.
  • status (optional/detected). Status filter or value. Default: ''.
• Response: success comment(s): OK.
• Notable errors: Drop has expired; Only reserved or active drops may be revoked; Principal id is unavailable; Drop not found; Invalid.

POST /v1/drop/status

Gets status for drop.

• Handler: thisProject\api\drop\Status
• Source: lib/php/thisProject/api/drop/Status.php
• Delegates to: lib/php/thisProject/service/Drop.php::status
• Auth: principal route rule: user, admin, root
• Detected request fields:
  • id (required). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
• Response: success comment(s): OK.
• Notable errors: Principal id is unavailable; Drop not found; Invalid.

POST /v1/drop/store

Stores drop.

• Handler: thisProject\api\drop\Store
• Source: lib/php/thisProject/api/drop/Store.php
• Delegates to: lib/php/thisProject/service/Drop.php::store
• Auth: principal route rule: user, admin, root
• Detected request fields:
  • data (required). Payload/data value. Default: null.
  • payload (required). Payload to store or encrypt. Default: null.
  • anonymous (optional/detected). Whether the resource can be consumed anonymously. Default: false.
  • content_type (optional/detected). MIME content type override. Default: null.
  • expires (optional/detected). Expiration timestamp.
  • expires_at (optional/detected). Expiration timestamp.
  • id (optional/detected). Record identifier. Many handlers accept this as the primary lookup key. Default: ''.
  • key (optional/detected). Key id/name or drop encryption key depending on the endpoint. Default: ''.
  • kind (optional/detected). Type/kind discriminator. Default: null.
  • metadata (optional/detected). Caller-supplied metadata object. Default: null.
  • payload_format (optional/detected). Payload format such as json, text, html, or base64. Default: ''.
  • ttl (optional/detected). Time-to-live in seconds. Default: ''.
• Response: success comment(s): OK.
• Notable errors: Drop id already exists; Principal id is unavailable; Missing payload; Invalid payload_format; Invalid ttl; Invalid.