Dify app metadata and files

Use this family to inspect a published application’s contract, read one Dify end user, upload one bounded user file, or retrieve one bounded file preview. All seven operations are available for every supported app mode.

Choose the configured app through the capability ID. The host supplies its app-specific Bearer key and fixed provider origin.

Choose an operation

The capability template is:

cap:dify:<app_id>:<operation>

Use discovery to obtain the exact app ID. Do not insert a provider key, origin, or unrelated app ID into the Action.

Partition input correctly

Every operation accepts the generic frozen input object:

Path values contain 1 to 512 bytes. user contains 1 to 256 bytes without control characters. Query objects have at most 128 properties and arrays at most 256 scalar values.

The connector appends the required preview user itself and rejects a conflicting query value.

Read app metadata

Use the four metadata reads to answer different questions:

All four send an authenticated empty-path read to the selected app. They do not require Dify end-user identity and do not prove that model execution, file access, or another app key works.

Each result has the generic JSON shape:

{
  "http_status": 200,
  "body": {},
  "content_type": "application/json",
  "provider_request_id": null
}

The provider owns the nested body schema. Treat unknown fields as compatible provider data unless the selected task requires a stronger reviewed contract.

Read one end user

Select end_user.get and supply only the provider’s end-user identifier:

{
  "end_user_id": "end-user-identifier"
}

This route does not use the caller’s user field. Authorization comes from the selected app key and AIP tenant policy. A returned record can contain personal data, so apply the connector’s confidential and redaction-required contract.

An absent or wrong identifier is a read failure. It is not evidence that the same person has no conversations, messages, files, or state under another app.

Upload one file

Before upload:

1. select the intended app and stable tenant-scoped end-user value;
2. confirm the file is authorized for that user and Dify application;
3. calculate the decoded size and intended content type;
4. create one Action ID and one idempotency key;
5. obtain the required tenant-policy approval.

The Action input has this shape:

{
  "user": "tenant-user-0190",
  "file": {
    "filename": "context.txt",
    "content_type": "text/plain",
    "content_base64": "ZXhhbXBsZQ=="
  }
}

The connector validates a safe basename, base64, content type, and decoded size. It sends multipart fields named file and user. For this operation it does not serialize Action body as a multipart data field.

The decoded-file implementation limit is 32 MiB. The base64 schema and common native envelope can impose lower effective limits. Do not raise a response limit to work around an oversized request.

Upload is a provider mutation. It requires approval and a tenant-scoped key, publishes no automatic retry, and has no rollback capability. After an interrupted response, inspect provider and Action state before another upload.

Preview one message file

Supply the file and the same stable Dify user identity that owns access:

{
  "file_id": "file-identifier",
  "user": "tenant-user-0190"
}

The connector renders file_id in the path and user in the query. It returns bounded bytes as base64:

{
  "http_status": 200,
  "content_base64": "ZXhhbXBsZQ==",
  "content_type": "text/plain",
  "size_bytes": 7,
  "provider_request_id": null
}

Decode only after authorization, content-type policy, malware controls, and output-size checks. The connector does not write the result to a caller-selected path.

Recover safely

For reads, retry support still requires the same Action policy, budget, and verified error. For upload, neither a key nor approval authorizes automatic replay.

Related documentation

• Dify capability index
• Dify connector configuration
• Authentication and credential scopes
• Dify connector overview
• Errors and retry decisions