Flatfile · Capability
API Reference — subpackage_mapping
API Reference — subpackage_mapping. 13 operations. Lead operation: Create a mapping between two schemas. Self-contained Naftiko capability covering one Flatfile business surface.
What You Can Do
POST
Createmappingprogram
— Create a mapping between two schemas
/v1/mapping
DELETE
Deleteallhistoryforuser
— Delete all history for the authenticated user
/v1/mapping
GET
Listmappingprograms
— List mapping programs
/v1/mapping
GET
Getmappingprogram
— Get a mapping program
/v1/mapping/{programid}
PATCH
Updatemappingprogram
— Update a mapping program
/v1/mapping/{programid}
DELETE
Deletemappingprogram
— Delete a mapping program
/v1/mapping/{programid}
POST
Createrules
— Add mapping rules to a program
/v1/mapping/{programid}/rules
DELETE
Deletemultiplerules
— Delete multiple mapping rules
/v1/mapping/{programid}/rules
GET
Listrules
— List mapping rules
/v1/mapping/{programid}/rules
PATCH
Updaterules
— Update a list of mapping rules
/v1/mapping/{programid}/rules
GET
Getrule
— Get a mapping rule
/v1/mapping/{programid}/rules/{mappingid}
PATCH
Updaterule
— Update a mapping rule
/v1/mapping/{programid}/rules/{mappingid}
DELETE
Deleterule
— Delete a mapping rule
/v1/mapping/{programid}/rules/{mappingid}
MCP Tools
create-mapping-between-two-schemas
Create a mapping between two schemas
delete-all-history-authenticated-user
Delete all history for the authenticated user
idempotent
list-mapping-programs
List mapping programs
read-only
idempotent
get-mapping-program
Get a mapping program
read-only
idempotent
update-mapping-program
Update a mapping program
idempotent
delete-mapping-program
Delete a mapping program
idempotent
add-mapping-rules-program
Add mapping rules to a program
delete-multiple-mapping-rules
Delete multiple mapping rules
idempotent
list-mapping-rules
List mapping rules
read-only
idempotent
update-list-mapping-rules
Update a list of mapping rules
idempotent
get-mapping-rule
Get a mapping rule
read-only
idempotent
update-mapping-rule
Update a mapping rule
idempotent
delete-mapping-rule
Delete a mapping rule
idempotent
Capability Spec
naftiko: 1.0.0-alpha2
info:
label: API Reference — subpackage_mapping
description: 'API Reference — subpackage_mapping. 13 operations. Lead operation: Create a mapping between two schemas. Self-contained
Naftiko capability covering one Flatfile business surface.'
tags:
- Flatfile
- subpackage_mapping
created: '2026-05-19'
modified: '2026-05-19'
binds:
- namespace: env
keys:
FLATFILE_API_KEY: FLATFILE_API_KEY
capability:
consumes:
- type: http
namespace: flatfile-subpackage-mapping
baseUri: https://api.x.flatfile.com/v1
description: API Reference — subpackage_mapping business capability. Self-contained, no shared references.
resources:
- name: mapping
path: /mapping
operations:
- name: createmappingprogram
method: POST
description: Create a mapping between two schemas
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: environmentId
in: query
type: string
description: The ID of the environment
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: false
- name: deleteallhistoryforuser
method: DELETE
description: Delete all history for the authenticated user
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: false
- name: listmappingprograms
method: GET
description: List mapping programs
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: pageSize
in: query
type: integer
description: Number of programs to return in a page (default 10)
- name: pageNumber
in: query
type: integer
description: Based on pageSize, which page of records to return
- name: createdBy
in: query
type: string
description: Filter by creator
- name: createdAfter
in: query
type: string
description: Filter by creation time
- name: createdBefore
in: query
type: string
description: Filter by creation time
- name: environmentId
in: query
type: string
description: The ID of the environment
- name: jobId
in: query
type: string
description: A job ID to find mapping programs for
- name: familyId
in: query
type: string
description: Filter by family
- name: namespace
in: query
type: string
description: Filter by namespace
- name: sourceKeys
in: query
type: string
description: Filter by source keys
- name: destinationKeys
in: query
type: string
description: Filter by destination keys
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: mapping-programId
path: /mapping/{programId}
operations:
- name: getmappingprogram
method: GET
description: Get a mapping program
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: updatemappingprogram
method: PATCH
description: Update a mapping program
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: false
- name: deletemappingprogram
method: DELETE
description: Delete a mapping program
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: mapping-programId-rules
path: /mapping/{programId}/rules
operations:
- name: createrules
method: POST
description: Add mapping rules to a program
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: false
- name: deletemultiplerules
method: DELETE
description: Delete multiple mapping rules
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: false
- name: listrules
method: GET
description: List mapping rules
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: updaterules
method: PATCH
description: Update a list of mapping rules
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: false
- name: mapping-programId-rules-mappingId
path: /mapping/{programId}/rules/{mappingId}
operations:
- name: getrule
method: GET
description: Get a mapping rule
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: mappingId
in: path
type: string
description: ID of mapping rule
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: updaterule
method: PATCH
description: Update a mapping rule
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: mappingId
in: path
type: string
description: ID of mapping rule
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
- name: body
in: body
type: object
description: Request body (JSON).
required: false
- name: deleterule
method: DELETE
description: Delete a mapping rule
outputRawFormat: json
outputParameters:
- name: result
type: object
value: $.
inputParameters:
- name: programId
in: path
type: string
description: ID of the program
required: true
- name: mappingId
in: path
type: string
description: ID of mapping rule
required: true
- name: Authorization
in: header
type: string
description: Bearer authentication
required: true
- name: X-Disable-Hooks
in: header
type: string
required: true
authentication:
type: bearer
token: '{{env.FLATFILE_API_KEY}}'
exposes:
- type: rest
namespace: flatfile-subpackage-mapping-rest
port: 8080
description: REST adapter for API Reference — subpackage_mapping. One Spectral-compliant resource per consumed operation,
prefixed with /v1.
resources:
- path: /v1/mapping
name: mapping
description: REST surface for mapping.
operations:
- method: POST
name: createmappingprogram
description: Create a mapping between two schemas
call: flatfile-subpackage-mapping.createmappingprogram
with:
environmentId: rest.environmentId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
body: rest.body
outputParameters:
- type: object
mapping: $.
- method: DELETE
name: deleteallhistoryforuser
description: Delete all history for the authenticated user
call: flatfile-subpackage-mapping.deleteallhistoryforuser
with:
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
body: rest.body
outputParameters:
- type: object
mapping: $.
- method: GET
name: listmappingprograms
description: List mapping programs
call: flatfile-subpackage-mapping.listmappingprograms
with:
pageSize: rest.pageSize
pageNumber: rest.pageNumber
createdBy: rest.createdBy
createdAfter: rest.createdAfter
createdBefore: rest.createdBefore
environmentId: rest.environmentId
jobId: rest.jobId
familyId: rest.familyId
namespace: rest.namespace
sourceKeys: rest.sourceKeys
destinationKeys: rest.destinationKeys
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- path: /v1/mapping/{programid}
name: mapping-programid
description: REST surface for mapping-programId.
operations:
- method: GET
name: getmappingprogram
description: Get a mapping program
call: flatfile-subpackage-mapping.getmappingprogram
with:
programId: rest.programId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- method: PATCH
name: updatemappingprogram
description: Update a mapping program
call: flatfile-subpackage-mapping.updatemappingprogram
with:
programId: rest.programId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
body: rest.body
outputParameters:
- type: object
mapping: $.
- method: DELETE
name: deletemappingprogram
description: Delete a mapping program
call: flatfile-subpackage-mapping.deletemappingprogram
with:
programId: rest.programId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- path: /v1/mapping/{programid}/rules
name: mapping-programid-rules
description: REST surface for mapping-programId-rules.
operations:
- method: POST
name: createrules
description: Add mapping rules to a program
call: flatfile-subpackage-mapping.createrules
with:
programId: rest.programId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
body: rest.body
outputParameters:
- type: object
mapping: $.
- method: DELETE
name: deletemultiplerules
description: Delete multiple mapping rules
call: flatfile-subpackage-mapping.deletemultiplerules
with:
programId: rest.programId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
body: rest.body
outputParameters:
- type: object
mapping: $.
- method: GET
name: listrules
description: List mapping rules
call: flatfile-subpackage-mapping.listrules
with:
programId: rest.programId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- method: PATCH
name: updaterules
description: Update a list of mapping rules
call: flatfile-subpackage-mapping.updaterules
with:
programId: rest.programId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
body: rest.body
outputParameters:
- type: object
mapping: $.
- path: /v1/mapping/{programid}/rules/{mappingid}
name: mapping-programid-rules-mappingid
description: REST surface for mapping-programId-rules-mappingId.
operations:
- method: GET
name: getrule
description: Get a mapping rule
call: flatfile-subpackage-mapping.getrule
with:
programId: rest.programId
mappingId: rest.mappingId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- method: PATCH
name: updaterule
description: Update a mapping rule
call: flatfile-subpackage-mapping.updaterule
with:
programId: rest.programId
mappingId: rest.mappingId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
body: rest.body
outputParameters:
- type: object
mapping: $.
- method: DELETE
name: deleterule
description: Delete a mapping rule
call: flatfile-subpackage-mapping.deleterule
with:
programId: rest.programId
mappingId: rest.mappingId
Authorization: rest.Authorization
X-Disable-Hooks: rest.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- type: mcp
namespace: flatfile-subpackage-mapping-mcp
port: 9090
transport: http
description: MCP adapter for API Reference — subpackage_mapping. One tool per consumed operation, routed inline through
this capability's consumes block.
tools:
- name: create-mapping-between-two-schemas
description: Create a mapping between two schemas
hints:
readOnly: false
destructive: false
idempotent: false
call: flatfile-subpackage-mapping.createmappingprogram
with:
environmentId: tools.environmentId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
body: tools.body
outputParameters:
- type: object
mapping: $.
- name: delete-all-history-authenticated-user
description: Delete all history for the authenticated user
hints:
readOnly: false
destructive: true
idempotent: true
call: flatfile-subpackage-mapping.deleteallhistoryforuser
with:
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
body: tools.body
outputParameters:
- type: object
mapping: $.
- name: list-mapping-programs
description: List mapping programs
hints:
readOnly: true
destructive: false
idempotent: true
call: flatfile-subpackage-mapping.listmappingprograms
with:
pageSize: tools.pageSize
pageNumber: tools.pageNumber
createdBy: tools.createdBy
createdAfter: tools.createdAfter
createdBefore: tools.createdBefore
environmentId: tools.environmentId
jobId: tools.jobId
familyId: tools.familyId
namespace: tools.namespace
sourceKeys: tools.sourceKeys
destinationKeys: tools.destinationKeys
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- name: get-mapping-program
description: Get a mapping program
hints:
readOnly: true
destructive: false
idempotent: true
call: flatfile-subpackage-mapping.getmappingprogram
with:
programId: tools.programId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- name: update-mapping-program
description: Update a mapping program
hints:
readOnly: false
destructive: false
idempotent: true
call: flatfile-subpackage-mapping.updatemappingprogram
with:
programId: tools.programId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
body: tools.body
outputParameters:
- type: object
mapping: $.
- name: delete-mapping-program
description: Delete a mapping program
hints:
readOnly: false
destructive: true
idempotent: true
call: flatfile-subpackage-mapping.deletemappingprogram
with:
programId: tools.programId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- name: add-mapping-rules-program
description: Add mapping rules to a program
hints:
readOnly: false
destructive: false
idempotent: false
call: flatfile-subpackage-mapping.createrules
with:
programId: tools.programId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
body: tools.body
outputParameters:
- type: object
mapping: $.
- name: delete-multiple-mapping-rules
description: Delete multiple mapping rules
hints:
readOnly: false
destructive: true
idempotent: true
call: flatfile-subpackage-mapping.deletemultiplerules
with:
programId: tools.programId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
body: tools.body
outputParameters:
- type: object
mapping: $.
- name: list-mapping-rules
description: List mapping rules
hints:
readOnly: true
destructive: false
idempotent: true
call: flatfile-subpackage-mapping.listrules
with:
programId: tools.programId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- name: update-list-mapping-rules
description: Update a list of mapping rules
hints:
readOnly: false
destructive: false
idempotent: true
call: flatfile-subpackage-mapping.updaterules
with:
programId: tools.programId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
body: tools.body
outputParameters:
- type: object
mapping: $.
- name: get-mapping-rule
description: Get a mapping rule
hints:
readOnly: true
destructive: false
idempotent: true
call: flatfile-subpackage-mapping.getrule
with:
programId: tools.programId
mappingId: tools.mappingId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.
- name: update-mapping-rule
description: Update a mapping rule
hints:
readOnly: false
destructive: false
idempotent: true
call: flatfile-subpackage-mapping.updaterule
with:
programId: tools.programId
mappingId: tools.mappingId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
body: tools.body
outputParameters:
- type: object
mapping: $.
- name: delete-mapping-rule
description: Delete a mapping rule
hints:
readOnly: false
destructive: true
idempotent: true
call: flatfile-subpackage-mapping.deleterule
with:
programId: tools.programId
mappingId: tools.mappingId
Authorization: tools.Authorization
X-Disable-Hooks: tools.X-Disable-Hooks
outputParameters:
- type: object
mapping: $.