개발자 가이드
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 explicitacceptextension list. - Fields: Up to 16 named parameters (with up to 8 visible to callers), supporting
enum,number,boolean,text(≤ 100000 chars, optionally multiline), andjson(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 bindin: pathfields. Assembled URL ≤ 8 KB. - Body Encoding: Supports none, json, form, multipart, raw, envelope. Field values are placed according to each field's
inlocation. - 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:
- Connect: Connect to
https://518.plus/mcpwith an API key or OAuth credential carrying thetools:publishcapability. - Submit Manifest: Call
publish_tool. The new tool lands in unlisted (private test) mode and is immediately callable via its returned key. - Self-Verification: Call
tools/callonce on your new tool (author self-tests are free). A single successful run unlocks public marketplace visibility. - Go Public: Call
update_toolwith{"visibility": "public"}to launch on the public market. - Manage: Use
list_my_tools,get_my_tool,tool_call_log, anddelete_toolfor 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 toolsPOST /v1/usertools— Create a tool (submit manifest)GET /v1/usertools/{key}— Retrieve config and runtime facts ({manifest, readonly})PATCH /v1/usertools/{key}— Partially update fieldsDELETE /v1/usertools/{key}— Remove toolGET /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:
| Field | Type | Description |
|---|---|---|
label | LocalizedText (string | object) | Tool name shown in the market and to agents: a string or a {locale: text} object |
desc | LocalizedText (string | object) | What the tool does, what it takes and what it returns: a string or a {locale: text} object |
url | string | Your 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 |
method | enum: GET, POST | GET admits no request body and no in:body fields |
body | enum: none, json, form, multipart, raw, envelope | How 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_s | integer | Seconds the platform waits for your endpoint to answer |
auth_in | enum: header, query | Where the credential rides |
auth_name | string | Name 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_token | string | Value 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 |
cost | integer | Price per call in credits (1000 credits = US$1); 0 = free |
visibility | enum: private, unlisted, public | private = 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) |
enabled | boolean | Whether the tool accepts calls |
files_min | integer | Fewest attachments per call |
files_max | integer | Most attachments per call; 0 declares a no-attachment tool |
accept | array (max — items) | Attachments: accepted extensions, lowercase with a leading dot (e.g. .png); all must belong to the format_families category |
format_families | enum: image, document, data, text, audio, video, cad3d, archive, all | Attachments: the input category (one key; it also sets the tool icon) |
fields | array (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` |
outputs | array (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 withfiles_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/toolsandGET /v1/tools/{key}— Read catalog entries and single-tool schemas.POST /v1/tools/{key}— Execute a tool via JSON ({"params", "files"}) ormultipart/form-data(fileparts + named field parts). SendIdempotency-Key(acts asclient_ref) and optionalX-518-Expiry-Days/X-518-Allowed-Downloadsheaders.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-Keyrequired on order creation).
6. HTTP Contract & Response Handling
Southbound Request Assembly:
none: No body (GET).json:in: bodyfields 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: bodyfields as form fields; attachments as direct file parts matching uploaded bytes.raw: The singlein: bodyfield 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 (supportingdata_b64orurl).application/jsonandapplication/*+json: Single JSON item.text/*: Single text item (text/htmlandapplication/xhtml+xmlland 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}:
| Code | Description & Guidance |
|---|---|
bad_label | The tool name is missing, empty or longer than 40 characters. |
bad_desc | The description is invalid (over 200 characters per language or wrong shape). |
https_required | The endpoint must be an https URL on a public address. |
bad_url | The endpoint URL is invalid. |
bad_timeout | timeout_s must be an integer between 5 and 300. |
bad_auth_name | Something went wrong, please try again |
bad_auth_in | Something went wrong, please try again |
bad_method | Something went wrong, please try again |
bad_body_encoding | Something went wrong, please try again |
bad_files_range | Minimum files cannot exceed the maximum |
bad_accept | accept must be an explicit non-empty list of extensions inside the declared scenario's format group. |
bad_format_family | format_families must be a single scenario key. |
bad_binding | The request assembly is inconsistent: check method, body encoding, field locations and the endpoint's own query |
bad_outputs | Choose at least one output type |
bad_visibility | visibility must be private, unlisted or public. |
bad_cost | cost must be an integer between 0 and 100000. |
fields_too_many | Too many fields: max 16 per tool, 8 visible |
unknown_field | Unknown manifest field: it is not part of the publish manifest and is not accepted. |
needs_successful_run | Call your own tool successfully once before making it public. |
too_many_tools | You reached the limit of 20 tools. |
credential_vault_unavailable | Credential storage is temporarily unavailable — try again shortly. |
not_found | No 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 unlockspublic; 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.