Guide du développeur

Publier un outil

518.PLUS is a tool publishing and hosting platform for AI agents and web users. You host your HTTPS endpoint; the platform manages request assembly, credential encapsulation, SSRF-guarded transport, metering, and multi-item result delivery. This guide covers publishing tools over MCP, the REST API, and the web console, along with the manifest specification and southbound HTTP contract.

1. What a 518 Tool Is

A tool is a developer-hosted standard HTTPS endpoint. A tool's invocation is defined by two parts, with all southbound request behavior strictly declared:

  • Attachments: [files_min, files_max] (up to 20 files), with a format family tag and an explicit accept extension list.
  • Fields: Up to 16 named parameters (with up to 8 visible to callers), supporting enum, number, boolean, text (≤ 100000 chars, optionally multiline), and json (canonical JSON ≤ 100000 chars).

Request Assembly defines how a call becomes an HTTP request to your endpoint:

  • Method & URL: Supports GET / POST. Fixed query parameters may live directly in the endpoint URL; {key} path placeholders bind in: path fields. Assembled URL ≤ 8 KB.
  • Body Encoding: Supports none, json, form, multipart, raw, envelope. Field values are placed according to each field's in location.
  • Constant Fields (const): Fixed to their default value, invisible to callers, but always assembled into requests.
  • Credential Vault: Auth tokens are placed in Header or Query, securely sealed, and never leaked into logs or responses.

Individual file limit is 50 MB. Once published, tools are unified and callable across the web, MCP (/mcp), and the REST API (/v1).

2. Publishing via Agent (MCP)

The standard workflow:

  1. Connect: Connect to https://518.plus/mcp with an API key or OAuth credential carrying the tools:publish capability.
  2. Submit Manifest: Call publish_tool. The new tool lands in unlisted (private test) mode and is immediately callable via its returned key.
  3. Self-Verification: Call tools/call once on your new tool (author self-tests are free). A single successful run unlocks public marketplace visibility.
  4. Go Public: Call update_tool with {"visibility": "public"} to launch on the public market.
  5. Manage: Use list_my_tools, get_my_tool, tool_call_log, and delete_tool for lifecycle management and call audits.

Three representative manifest examples:

(a) GET API with fixed URL parameters and a multiline query field:

{
  "label": { "en": "Commons Search" },
  "url": "https://commons.wikimedia.org/w/api.php?action=query&list=search&format=json",
  "method": "GET",
  "body": "none",
  "cost": 0,
  "fields": [
    { "key": "srsearch", "type": "text", "multiline": true,
      "in": "query", "required": true,
      "label": { "en": "Search term" } } ]
}

(b) JSON POST API with a constant model parameter and a header credential:

{
  "label": { "en": "Describe Image" },
  "url": "https://api.example.com/v1/describe",
  "method": "POST",
  "body": "json",
  "timeout_s": 120,
  "auth_in": "header", "auth_name": "Authorization", "auth_token": "Bearer sk-…",
  "cost": 20,
  "files_min": 1, "files_max": 1, "format_families": "image", "accept": [".png", ".jpg"],
  "fields": [
    { "key": "model", "type": "enum", "const": true, "default": "v2",
      "in": "body", "options": [{"value": "v2", "label": "v2"}],
      "label": {"en": "Model"} },
    { "key": "detail", "type": "json", "in": "body",
      "label": { "en": "Extra options (JSON)" } },
    { "key": "image_url", "type": "text", "in": "body", "files": true,
      "label": { "en": "Image" } } ]
}

(c) Multipart file API with attachments sent under the designated slot field:

{
  "label": { "en": "REST Packager" },
  "url": "https://api.example.com/package",
  "method": "POST",
  "body": "multipart",
  "cost": 10,
  "files_min": 1, "files_max": 8, "format_families": "document", "accept": [".pdf"],
  "fields": [
    { "key": "docs", "type": "text", "in": "body", "files": true,
      "label": { "en": "Documents" } },
    { "key": "title", "type": "text", "in": "body",
      "label": { "en": "Package title" } } ]
}

Errors return uniformly via isError results under _meta.error = {code, field, message} (see Section 7).

3. Publishing via REST API or Web Console

REST API (/v1): Using an API key with tools:publish, isomorphic with MCP publishing tools:

  • GET /v1/usertools — List your tools
  • POST /v1/usertools — Create a tool (submit manifest)
  • GET /v1/usertools/{key} — Retrieve config and runtime facts ({manifest, readonly})
  • PATCH /v1/usertools/{key} — Partially update fields
  • DELETE /v1/usertools/{key} — Remove tool
  • GET /v1/usertools/{key}/calls — Inspect recent 20 calls by others

Web Console: Visit /account/tools/publish for one-click cURL import, interactive field editing, and live debugging.

4. Manifest Field Reference

Matches the JSON Schema advertised by the MCP publishing meta tools:

FieldTypeDescription
labelLocalizedText (string | object)Tool name shown in the market and to agents: a string or a {locale: text} object
descLocalizedText (string | object)What the tool does, what it takes and what it returns: a string or a {locale: text} object
urlstringYour https endpoint; its host must resolve to a public IP address. Fixed query parameters may live in the URL; path {key} placeholders bind in:path fields
methodenum: GET, POSTGET admits no request body and no in:body fields
bodyenum: none, json, form, multipart, raw, envelopeHow the request body is assembled: none (no body) / json (in:body fields as top-level keys) / form (urlencoded) / multipart (in:body fields as parts, attachments as file parts) / raw (the ONE in:body field is the whole body) / envelope (the 518 protocol {files, params}). Default: json without attachments, envelope with
timeout_sintegerSeconds the platform waits for your endpoint to answer
auth_inenum: header, queryWhere the credential rides
auth_namestringName of the one fixed credential header (or query key) sent to your endpoint (optional); header names are reserved and rejected: connection, content-length, content-type, expect, host, proxy-connection, te, trailer, transfer-encoding, upgrade, user-agent
auth_tokenstringValue of the credential: stored encrypted and never returned; a query-placed token never appears in logs or error details. Send auth_name and auth_token both as empty strings to clear the credential
costintegerPrice per call in credits (1000 credits = US$1); 0 = free
visibilityenum: private, unlisted, publicprivate = only you; unlisted = callable by anyone who has the key, not in the market; public = listed in the market (needs one successful call by you first)
enabledbooleanWhether the tool accepts calls
files_minintegerFewest attachments per call
files_maxintegerMost attachments per call; 0 declares a no-attachment tool
acceptarray (max — items)Attachments: accepted extensions, lowercase with a leading dot (e.g. .png); all must belong to the format_families category
format_familiesenum: image, document, data, text, audio, video, cad3d, archive, allAttachments: the input category (one key; it also sets the tool icon)
fieldsarray (max 16 items)Input fields (at most 16, of which 8 are visible to callers); their values are validated and assembled into the request per the field's `in`
outputsarray (max — items)Result kinds your endpoint may return

Text limits: label ≤ 40, desc ≤ 200 per language; auth_name ≤ 64, auth_token ≤ 4096. Numeric fields accept standard JSON numbers only.

5. Public Calling API (/v1) & Invocation Contract

Every caller surface (Web / MCP / REST) enforces the exact five-key invocation: {tool_id, files, params, delivery, client_ref}.

  • files: List of attachment references (omitted for tools with files_max = 0).
  • params: Non-constant visible fields (constant and attachment-slot fields reject caller input).
  • client_ref: Required non-empty string (≤ 128 chars) serving as the idempotent operation identity. Retries with the same key never double-charge.

Direct /v1 Caller Endpoints (Authorization: Bearer fsk_…, JSON errors, no CORS):

  • GET /v1/tools and GET /v1/tools/{key} — Read catalog entries and single-tool schemas.
  • POST /v1/tools/{key} — Execute a tool via JSON ({"params", "files"}) or multipart/form-data (file parts + named field parts). Send Idempotency-Key (acts as client_ref) and optional X-518-Expiry-Days / X-518-Allowed-Downloads headers.
  • GET /v1/balance — Query spendable credit balance and 24h upload quota usage.
  • GET/POST /v1/topup/crypto/… — Programmatic stablecoin credit/tier orders (options, orders, orders/{id}, orders/{id}/paid, orders/{id}/cancel; Idempotency-Key required on order creation).

6. HTTP Contract & Response Handling

Southbound Request Assembly:

  • none: No body (GET).
  • json: in: body fields become top-level JSON keys; attachments arrive as temporary signed fetch URLs in the slot field.
  • form: URL-encoded parameters and attachment fetch URLs.
  • multipart: in: body fields as form fields; attachments as direct file parts matching uploaded bytes.
  • raw: The single in: body field is the full request body (text as UTF-8, JSON as canonical bytes).
  • envelope: 518 standard envelope protocol {"files": [...], "params": {...}}.

Response Interpretation (by Content-Type):

  • application/vnd.518.items+json: Multi-item result envelope (supporting data_b64 or url).
  • application/json and application/*+json: Single JSON item.
  • text/*: Single text item (text/html and application/xhtml+xml land as file items to prevent XSS).
  • Other binary types: Stored as file items, extracting names from Content-Disposition and sniffing byte signatures.
  • Empty 2xx responses or text items > 1 MB without declared file output fail the call.

Upstream Failures & Circuit Breaker:

  • Non-2xx Upstream: Platform returns HTTP 502 with upstream status and the first 4 KB of response body.
  • Upstream Timeout: Platform returns HTTP 504.
  • Auto-Pause: Timeouts, network/DNS unreachable, upstream 5xx, 401/403 auth failures, and non-conforming responses count toward failure streaks. Three consecutive counting failures within 10 minutes under the same configuration automatically pause public supply; one successful test run by the author allows resuming supply.

7. Publishing Errors

Every publishing surface returns the same structured triple {code, field, message}:

CodeDescription & Guidance
bad_labelThe tool name is missing, empty or longer than 40 characters.
bad_descThe description is invalid (over 200 characters per language or wrong shape).
https_requiredThe endpoint must be an https URL on a public address.
bad_urlThe endpoint URL is invalid.
bad_timeouttimeout_s must be an integer between 5 and 300.
bad_auth_nameSomething went wrong, please try again
bad_auth_inSomething went wrong, please try again
bad_methodSomething went wrong, please try again
bad_body_encodingSomething went wrong, please try again
bad_files_rangeMinimum files cannot exceed the maximum
bad_acceptaccept must be an explicit non-empty list of extensions inside the declared scenario's format group.
bad_format_familyformat_families must be a single scenario key.
bad_bindingThe request assembly is inconsistent: check method, body encoding, field locations and the endpoint's own query
bad_outputsChoose at least one output type
bad_visibilityvisibility must be private, unlisted or public.
bad_costcost must be an integer between 0 and 100000.
fields_too_manyToo many fields: max 16 per tool, 8 visible
unknown_fieldUnknown manifest field: it is not part of the publish manifest and is not accepted.
needs_successful_runCall your own tool successfully once before making it public.
too_many_toolsYou reached the limit of 20 tools.
credential_vault_unavailableCredential storage is temporarily unavailable — try again shortly.
not_foundNo such tool under your account.

8. Economics & Lifecycle

  • Pricing: 0–100000 credits per call (1,000 credits = $1.00 USD); 0 is free.
  • Earnings: Paid calls deduct platform commission (currently 20%), with net revenue credited instantly to your earnings pool.
  • Withdrawals: Request withdrawals once balance reaches $10.00.
  • Failure Refund: Failed calls are 100% refunded to the caller. Author self-tests are free and yield no revenue.
  • Lifecycle: New tools land as unlisted; self-verification unlocks public; supports enable/disable and deletion. Up to 20 tools per account.

9. Platform Boundaries & Non-Goals

  • Synchronous only: Every call is a single synchronous request/response; no polling for async jobs.
  • Full delivery: Answers are read whole and interpreted; no SSE streaming.
  • Fixed credentials: The platform manages one fixed credential per tool; no user OAuth proxying.
  • Zero mutation: What your endpoint returns is what callers receive; no arbitrary data mapping.
  • Single result set: Up to 20 items per call; no multi-page stream pagination.